@abot-ai/runtime 1.2.0 → 1.3.0

package/dist/src/runtime/steps/execution-agent/capability-decision-parsing.js

@@ -0,0 +1,165 @@
+import { CAPABILITY_INTENT_MAX_LENGTH, materializeCapabilityControlsIfComplete, validateCapabilitySelectionControls, } from "../../orchestration/capability-adapters/index.js";
+import { normalizeExecutionWorkingDirectory } from "../../orchestration/capability-adapters/working-directory.js";
+import { executionCapabilityControlsIssue, normalizeGeneratedExecutionCapabilityControls, parseExecutionOperationObjective, requiresExecutionOperationObjective, } from "./capability-invocation-contract.js";
+import { EXECUTION_AGENT_CAPABILITY_SCOPE_GROUP_COUNT_MAX, } from "./contracts.js";
+import { asRecord, exactKeys, issue, validateBoundedText, } from "./decision-validation.js";
+export function parseCapabilityCatalogGroupIds(value, offeredCatalogGroupIds, issues) {
+    if (!Array.isArray(value) ||
+        value.length === 0 ||
+        value.length > EXECUTION_AGENT_CAPABILITY_SCOPE_GROUP_COUNT_MAX ||
+        new Set(value).size !== value.length ||
+        value.some((entry) => typeof entry !== "string")) {
+        issues.push(issue("execution_agent_capability_scope_invalid", "decision.catalogGroupIds", `catalogGroupIds must contain 1-${EXECUTION_AGENT_CAPABILITY_SCOPE_GROUP_COUNT_MAX} distinct offered group ids.`));
+        return undefined;
+    }
+    const catalogGroupIds = value;
+    if (catalogGroupIds.some((groupId) => !offeredCatalogGroupIds.includes(groupId))) {
+        issues.push(issue("execution_agent_capability_scope_group_unavailable", "decision.catalogGroupIds", "Every catalogGroupId must identify one group offered for this exact scope action."));
+        return undefined;
+    }
+    return Object.freeze([...catalogGroupIds]);
+}
+export function parseCapabilityBatch(value, contract, issues) {
+    if (!Array.isArray(value) ||
+        value.length < 2 ||
+        contract.maxBatchCapabilityExecutions < 2 ||
+        value.length > contract.maxBatchCapabilityExecutions) {
+        issues.push(issue("execution_agent_capability_batch_invalid", "decision.invocations", `Observation batch must contain 2-${contract.maxBatchCapabilityExecutions} invocations.`));
+        return undefined;
+    }
+    const accepted = [];
+    const issueCountBeforeInvocations = issues.length;
+    value.forEach((invocation, index) => {
+        const parsed = parseCapabilityInvocation({
+            value: invocation,
+            path: `decision.invocations.${index}`,
+            capabilities: contract.capabilities,
+            observationOnly: true,
+            includesAction: false,
+            issues,
+        });
+        if (parsed.value)
+            accepted.push(parsed.value);
+    });
+    const invocationValidationFailed = accepted.length !== value.length ||
+        issues.length !== issueCountBeforeInvocations;
+    if (invocationValidationFailed)
+        return undefined;
+    return Object.freeze(accepted);
+}
+export function parseCapabilityInvocation(params) {
+    const record = asRecord(params.value);
+    const baseExpectedKeys = [
+        ...(params.includesAction ? ["action"] : []),
+        "capabilityId",
+        "intent",
+    ];
+    if (!record) {
+        params.issues.push(issue("execution_agent_capability_invocation_invalid", params.path, "Capability invocation must be an object."));
+        return { expectedKeys: baseExpectedKeys };
+    }
+    let capability;
+    if (typeof record.capabilityId !== "string") {
+        params.issues.push(issue("execution_agent_capability_id_invalid", `${params.path}.capabilityId`, "capabilityId must identify one available capability."));
+    }
+    else {
+        capability = params.capabilities.find(({ capabilityId }) => capabilityId === record.capabilityId);
+        if (!capability) {
+            params.issues.push(issue("execution_agent_capability_unavailable", `${params.path}.capabilityId`, "capabilityId must identify one available capability."));
+        }
+        else if (params.observationOnly && capability.effect !== "observation") {
+            params.issues.push(issue("execution_agent_capability_batch_effect_invalid", `${params.path}.capabilityId`, "Only observation capabilities may be invoked in a batch."));
+        }
+    }
+    const expectedKeys = [
+        ...baseExpectedKeys,
+        ...(capability && requiresExecutionOperationObjective(capability.partition)
+            ? ["operationObjective"]
+            : []),
+        ...(capability?.partition.selectionControlIds.length
+            ? ["selectionControls"]
+            : []),
+    ];
+    if (!params.includesAction) {
+        exactKeys(record, expectedKeys, params.issues, params.path);
+    }
+    const intent = validateBoundedText({
+        value: record.intent,
+        maximumLength: CAPABILITY_INTENT_MAX_LENGTH,
+        code: "execution_agent_capability_intent_invalid",
+        path: `${params.path}.intent`,
+        label: "Capability intent",
+        issues: params.issues,
+    });
+    const operationObjective = parseExecutionOperationObjective({
+        value: record.operationObjective,
+        required: capability !== undefined &&
+            requiresExecutionOperationObjective(capability.partition),
+        path: `${params.path}.operationObjective`,
+        issues: params.issues,
+    });
+    let selectionControls;
+    let controls;
+    if (capability) {
+        const normalizedSelectionControls = capability.partition.selectionControlIds.length > 0
+            ? normalizeGeneratedExecutionCapabilityControls(record.selectionControls, capability.partition.selectionSchema)
+            : {};
+        const selection = validateCapabilitySelectionControls(capability.partition, normalizedSelectionControls);
+        if (!selection.ok) {
+            params.issues.push(executionCapabilityControlsIssue({
+                issueCode: selection.issueCode,
+                controlId: selection.controlId,
+                path: selection.controlId
+                    ? `${params.path}.selectionControls.${selection.controlId}`
+                    : `${params.path}.selectionControls`,
+            }));
+        }
+        else {
+            if (capability.partition.selectionControlIds.length > 0) {
+                selectionControls = selection.value;
+            }
+            const materialized = materializeCapabilityControlsIfComplete(capability.partition, selection.value);
+            if (materialized && !materialized.ok) {
+                params.issues.push(executionCapabilityControlsIssue({
+                    issueCode: materialized.issueCode,
+                    controlId: materialized.controlId,
+                    path: materialized.controlId
+                        ? `${params.path}.selectionControls.${materialized.controlId}`
+                        : `${params.path}.selectionControls`,
+                }));
+            }
+            else if (materialized?.ok) {
+                controls = materialized.value;
+            }
+        }
+    }
+    if (!capability ||
+        (params.observationOnly && capability.effect !== "observation") ||
+        intent === undefined ||
+        !operationObjective.ok) {
+        return { expectedKeys };
+    }
+    return {
+        expectedKeys,
+        value: Object.freeze({
+            capabilityId: capability.capabilityId,
+            intent,
+            ...(operationObjective.value
+                ? { operationObjective: operationObjective.value }
+                : {}),
+            ...(selectionControls ? { selectionControls } : {}),
+            ...(controls ? { controls } : {}),
+        }),
+    };
+}
+export function parseWorkingDirectory(record, contract, issues) {
+    if (!contract.includeWorkingDirectory)
+        return undefined;
+    if (record.workingDirectory === null)
+        return ".";
+    const normalized = normalizeExecutionWorkingDirectory(record.workingDirectory);
+    if (!normalized) {
+        issues.push(issue("execution_agent_working_directory_invalid", "decision.workingDirectory", "workingDirectory must be one safe agent-root-relative directory."));
+    }
+    return normalized;
+}

package/dist/src/runtime/steps/execution-agent/contracts.d.ts

@@ -1,3 +1,4 @@
+import type { MemoryRecallDecision } from "../memory-recall-decision.js";
 import type { RoleCapabilitySelectionProjection, RoleCapabilitySelectionReconsiderationCause } from "../../orchestration/role-calls/index.js";
 import { type CapabilityControls, type CapabilityDescriptor } from "../../orchestration/capability-adapters/index.js";
 export declare const EXECUTION_AGENT_DECISION_MODEL_STEP: "execution.decision";
@@ -58,7 +59,7 @@ export type ExecutionAgentInvokeAuditorDecision = Readonly<ExecutionAgentDecisio
     action: "invoke_auditor";
     criterionIds: readonly string[];
 }>;
-export type ExecutionAgentDecision = ExecutionAgentOpenCapabilityScopeDecision | ExecutionAgentExtendCapabilityScopeDecision | ExecutionAgentRespondDecision | ExecutionAgentBlockedDecision | ExecutionAgentInvokeCapabilityDecision | ExecutionAgentInvokeCapabilitiesDecision | ExecutionAgentInvokePlannerDecision | ExecutionAgentInvokeAuditorDecision;
+export type ExecutionAgentDecision = MemoryRecallDecision | ExecutionAgentOpenCapabilityScopeDecision | ExecutionAgentExtendCapabilityScopeDecision | ExecutionAgentRespondDecision | ExecutionAgentBlockedDecision | ExecutionAgentInvokeCapabilityDecision | ExecutionAgentInvokeCapabilitiesDecision | ExecutionAgentInvokePlannerDecision | ExecutionAgentInvokeAuditorDecision;
 /** Runtime-only transition emitted when controls refinement exhausts validation. */
 export type ExecutionAgentReconsiderCapabilitySelectionDecision = Readonly<{
     action: "reconsider_capability_selection";
@@ -94,6 +95,7 @@ export type ExecutionAgentDecisionContractOptions = Readonly<{
     includeAcknowledgement?: boolean;
     includeTitle?: boolean;
     allowRespond?: boolean;
+    allowMemoryRecall?: boolean;
     allowPlanner?: boolean;
     allowAuditor?: boolean;
     availableAuditCriterionIds?: readonly string[];

package/dist/src/runtime/steps/execution-agent/decision-parsing.d.ts

@@ -0,0 +1,2 @@
+import { type ExecutionAgentDecisionContractOptions, type ExecutionAgentDecisionParseResult } from "./contracts.js";
+export declare function parseExecutionAgentDecisionOutput(text: string, options?: ExecutionAgentDecisionContractOptions): ExecutionAgentDecisionParseResult;

package/dist/src/runtime/steps/execution-agent/decision-parsing.js

@@ -0,0 +1,195 @@
+import { readStructuredDecisionEnvelope } from "../../model/structured-decision-envelope.js";
+import { isMemoryRecallDecisionRecord, parseMemoryRecallDecision, } from "../memory-recall-decision.js";
+import { EXECUTION_AGENT_ACKNOWLEDGEMENT_MAX_LENGTH, EXECUTION_AGENT_TITLE_MAX_LENGTH, EXECUTION_AGENT_AUDIT_CRITERION_COUNT_MAX, EXECUTION_AGENT_AUDIT_CRITERION_ID_MAX_LENGTH, EXECUTION_AGENT_DECISION_ACTIONS, EXECUTION_AGENT_RESPONSE_MAX_LENGTH, } from "./contracts.js";
+import { prepareExecutionAgentDecisionContract } from "./format.js";
+import { parseCapabilityCatalogGroupIds, parseCapabilityBatch, parseCapabilityInvocation, parseWorkingDirectory, } from "./capability-decision-parsing.js";
+import { parsePresentation, presentationKeys, exactPresentationKeys, validateObjective, parseBoundedTextArray, validateBoundedText, readAction, exactKeys, rejectEnvelope, issue, asRecord, deepFreeze, } from "./decision-validation.js";
+export function parseExecutionAgentDecisionOutput(text, options = {}) {
+    const contract = prepareExecutionAgentDecisionContract(options);
+    let decoded;
+    try {
+        decoded = JSON.parse(text.trim());
+    }
+    catch {
+        return rejectEnvelope([
+            issue("execution_agent_output_not_json", "decision", "Expected one JSON object."),
+        ]);
+    }
+    if (!asRecord(decoded)) {
+        return rejectEnvelope([
+            issue("execution_agent_output_not_object", "decision", "Expected one JSON object."),
+        ]);
+    }
+    const record = readStructuredDecisionEnvelope(decoded);
+    if (!record) {
+        return rejectEnvelope([
+            issue("execution_agent_output_envelope_invalid", "decision", "Expected exactly one decision object inside the canonical envelope."),
+        ]);
+    }
+    if (isMemoryRecallDecisionRecord(record)) {
+        return parseMemoryRecallDecision(record, {
+            allowMemoryRecall: contract.allowMemoryRecall,
+            includeAcknowledgement: contract.includeAcknowledgement,
+            includeTitle: contract.includeTitle,
+            acknowledgementMaxLength: EXECUTION_AGENT_ACKNOWLEDGEMENT_MAX_LENGTH,
+            titleMaxLength: EXECUTION_AGENT_TITLE_MAX_LENGTH,
+        });
+    }
+    const issues = [];
+    const selectedAction = readAction(record.action);
+    if (!selectedAction) {
+        issues.push(issue("execution_agent_action_invalid", "decision.action", `Action must be one of: ${EXECUTION_AGENT_DECISION_ACTIONS.join(", ")}.`));
+    }
+    const presentation = parsePresentation(record, contract, issues);
+    let decision;
+    if (selectedAction === "open_capability_scope") {
+        exactKeys(record, ["action", "catalogGroupIds", ...presentationKeys(contract)], issues, "decision");
+        const catalogGroupIds = parseCapabilityCatalogGroupIds(record.catalogGroupIds, contract.capabilityCatalogGroupIds, issues);
+        if (contract.activeCapabilityCatalogGroupIds !== null ||
+            contract.capabilityCatalogGroupIds.length === 0) {
+            issues.push(issue("execution_agent_capability_scope_open_unavailable", "decision.action", "open_capability_scope is available only while the canonical capability scope is closed."));
+        }
+        if (catalogGroupIds) {
+            decision = {
+                action: "open_capability_scope",
+                catalogGroupIds,
+                ...presentation,
+            };
+        }
+    }
+    else if (selectedAction === "respond") {
+        exactKeys(record, ["action", ...presentationKeys(contract)], issues, "decision");
+        if (!contract.allowRespond) {
+            issues.push(issue("execution_agent_response_not_allowed", "decision.action", "respond is not available until the canonical completion gate is open."));
+        }
+        decision = {
+            action: "respond",
+            ...presentation,
+        };
+    }
+    else if (selectedAction === "blocked") {
+        exactKeys(record, ["action", "response", ...presentationKeys(contract)], issues, "decision");
+        const response = validateBoundedText({
+            value: record.response,
+            maximumLength: EXECUTION_AGENT_RESPONSE_MAX_LENGTH,
+            code: "execution_agent_response_invalid",
+            path: "decision.response",
+            label: "Response",
+            issues,
+        });
+        if (response !== undefined) {
+            decision = {
+                action: "blocked",
+                response,
+                ...presentation,
+            };
+        }
+    }
+    else if (selectedAction === "invoke_capability") {
+        const invocation = parseCapabilityInvocation({
+            value: record,
+            path: "decision",
+            capabilities: contract.capabilities,
+            observationOnly: false,
+            includesAction: true,
+            issues,
+        });
+        exactPresentationKeys(record, contract, [
+            ...invocation.expectedKeys,
+            ...(contract.includeWorkingDirectory ? ["workingDirectory"] : []),
+        ], issues);
+        const workingDirectory = parseWorkingDirectory(record, contract, issues);
+        if (invocation.value) {
+            decision = {
+                action: "invoke_capability",
+                ...invocation.value,
+                ...(workingDirectory ? { workingDirectory } : {}),
+                ...presentation,
+            };
+        }
+    }
+    else if (selectedAction === "invoke_capabilities") {
+        exactKeys(record, [
+            "action",
+            "invocations",
+            ...(contract.includeWorkingDirectory ? ["workingDirectory"] : []),
+            ...presentationKeys(contract),
+        ], issues, "decision");
+        const invocations = parseCapabilityBatch(record.invocations, contract, issues);
+        const workingDirectory = parseWorkingDirectory(record, contract, issues);
+        if (invocations) {
+            decision = {
+                action: "invoke_capabilities",
+                invocations,
+                ...(workingDirectory ? { workingDirectory } : {}),
+                ...presentation,
+            };
+        }
+    }
+    else if (selectedAction === "extend_capability_scope") {
+        exactKeys(record, ["action", "catalogGroupIds", ...presentationKeys(contract)], issues, "decision");
+        const catalogGroupIds = parseCapabilityCatalogGroupIds(record.catalogGroupIds, contract.inactiveCapabilityCatalogGroupIds, issues);
+        if (contract.activeCapabilityCatalogGroupIds === null ||
+            contract.inactiveCapabilityCatalogGroupIds.length === 0) {
+            issues.push(issue("execution_agent_capability_scope_extend_unavailable", "decision.action", "extend_capability_scope is available only while a canonical capability scope is active and at least one inactive group is offered."));
+        }
+        if (catalogGroupIds) {
+            decision = {
+                action: "extend_capability_scope",
+                catalogGroupIds,
+                ...presentation,
+            };
+        }
+    }
+    else if (selectedAction === "invoke_planner") {
+        exactKeys(record, ["action", "objective", ...presentationKeys(contract)], issues, "decision");
+        if (!contract.allowPlanner) {
+            issues.push(issue("execution_agent_planner_not_allowed", "decision.action", "Planner invocation is not available for this decision."));
+        }
+        const objective = validateObjective(record.objective, issues);
+        if (objective !== undefined) {
+            decision = {
+                action: "invoke_planner",
+                objective,
+                ...presentation,
+            };
+        }
+    }
+    else if (selectedAction === "invoke_auditor") {
+        exactKeys(record, ["action", "criterionIds", ...presentationKeys(contract)], issues, "decision");
+        if (!contract.allowAuditor ||
+            contract.availableAuditCriterionIds.length === 0) {
+            issues.push(issue("execution_agent_auditor_not_allowed", "decision.action", "Auditor invocation is not available for this decision."));
+        }
+        const criterionIds = parseBoundedTextArray({
+            value: record.criterionIds,
+            path: "decision.criterionIds",
+            code: "execution_agent_audit_criteria_invalid",
+            label: "Audit criterion ids",
+            itemMaximumLength: EXECUTION_AGENT_AUDIT_CRITERION_ID_MAX_LENGTH,
+            maximumItems: EXECUTION_AGENT_AUDIT_CRITERION_COUNT_MAX,
+            issues,
+        });
+        if (criterionIds?.some((criterionId) => !contract.availableAuditCriterionIds.includes(criterionId))) {
+            issues.push(issue("execution_agent_audit_criteria_unavailable", "decision.criterionIds", "criterionIds must identify unresolved semantic criteria offered by the runtime."));
+        }
+        if (criterionIds) {
+            decision = {
+                action: "invoke_auditor",
+                criterionIds,
+                ...presentation,
+            };
+        }
+    }
+    if (issues.length > 0 || !decision) {
+        return {
+            ok: false,
+            stage: "domain_parser",
+            issues: Object.freeze(issues),
+        };
+    }
+    return {
+        ok: true,
+        decision: deepFreeze(structuredClone(decision)),
+    };
+}

package/dist/src/runtime/steps/execution-agent/decision-validation.d.ts

@@ -0,0 +1,30 @@
+import { type ExecutionAgentDecisionAction, type ExecutionAgentDecisionParseResult, type ExecutionAgentDecisionPresentation, type ExecutionAgentDecisionValidationIssue } from "./contracts.js";
+import type { PreparedExecutionAgentDecisionContract } from "./format.js";
+export declare function parsePresentation(record: Record<string, unknown>, contract: PreparedExecutionAgentDecisionContract, issues: ExecutionAgentDecisionValidationIssue[]): ExecutionAgentDecisionPresentation;
+export declare function presentationKeys(contract: PreparedExecutionAgentDecisionContract): readonly string[];
+export declare function exactPresentationKeys(record: Record<string, unknown>, contract: PreparedExecutionAgentDecisionContract, actionKeys: readonly string[], issues: ExecutionAgentDecisionValidationIssue[]): void;
+export declare function validateObjective(value: unknown, issues: ExecutionAgentDecisionValidationIssue[]): string | undefined;
+export declare function parseBoundedTextArray(params: Readonly<{
+    value: unknown;
+    path: string;
+    code: string;
+    label: string;
+    itemMaximumLength: number;
+    maximumItems: number;
+    issues: ExecutionAgentDecisionValidationIssue[];
+}>): readonly string[] | undefined;
+export declare function validateBoundedText(params: Readonly<{
+    value: unknown;
+    minimumLength?: number;
+    maximumLength: number;
+    code: string;
+    path: string;
+    label: string;
+    issues: ExecutionAgentDecisionValidationIssue[];
+}>): string | undefined;
+export declare function readAction(value: unknown): ExecutionAgentDecisionAction | undefined;
+export declare function exactKeys(record: Record<string, unknown>, expectedKeys: readonly string[], issues: ExecutionAgentDecisionValidationIssue[], path: string): void;
+export declare function rejectEnvelope(issues: readonly ExecutionAgentDecisionValidationIssue[]): ExecutionAgentDecisionParseResult;
+export declare function issue(code: string, path: string, message: string): ExecutionAgentDecisionValidationIssue;
+export declare function asRecord(value: unknown): Record<string, unknown> | undefined;
+export declare function deepFreeze<T>(value: T, seen?: WeakSet<object>): T;

package/dist/src/runtime/steps/execution-agent/decision-validation.js

@@ -0,0 +1,127 @@
+import { EXECUTION_AGENT_ACKNOWLEDGEMENT_MAX_LENGTH, EXECUTION_AGENT_TITLE_MAX_LENGTH, EXECUTION_AGENT_OBJECTIVE_MAX_LENGTH, EXECUTION_AGENT_DECISION_ACTIONS, } from "./contracts.js";
+export function parsePresentation(record, contract, issues) {
+    const acknowledgement = contract.includeAcknowledgement
+        ? validateBoundedText({
+            value: record.acknowledgement,
+            minimumLength: 2,
+            maximumLength: EXECUTION_AGENT_ACKNOWLEDGEMENT_MAX_LENGTH,
+            code: "execution_agent_acknowledgement_invalid",
+            path: "decision.acknowledgement",
+            label: "Acknowledgement",
+            issues,
+        })
+        : undefined;
+    const title = contract.includeTitle
+        ? validateBoundedText({
+            value: record.title,
+            minimumLength: 2,
+            maximumLength: EXECUTION_AGENT_TITLE_MAX_LENGTH,
+            code: "execution_agent_title_invalid",
+            path: "decision.title",
+            label: "Title",
+            issues,
+        })
+        : undefined;
+    return {
+        ...(contract.includeAcknowledgement && acknowledgement !== undefined
+            ? { acknowledgement }
+            : {}),
+        ...(contract.includeTitle && title !== undefined ? { title } : {}),
+    };
+}
+export function presentationKeys(contract) {
+    return [
+        ...(contract.includeAcknowledgement ? ["acknowledgement"] : []),
+        ...(contract.includeTitle ? ["title"] : []),
+    ];
+}
+export function exactPresentationKeys(record, contract, actionKeys, issues) {
+    exactKeys(record, [...actionKeys, ...presentationKeys(contract)], issues, "decision");
+}
+export function validateObjective(value, issues) {
+    return validateBoundedText({
+        value,
+        maximumLength: EXECUTION_AGENT_OBJECTIVE_MAX_LENGTH,
+        code: "execution_agent_objective_invalid",
+        path: "decision.objective",
+        label: "Objective",
+        issues,
+    });
+}
+export function parseBoundedTextArray(params) {
+    if (!Array.isArray(params.value) ||
+        params.value.length < 1 ||
+        params.value.length > params.maximumItems) {
+        params.issues.push(issue(params.code, params.path, `${params.label} must contain 1-${params.maximumItems} entries.`));
+        return undefined;
+    }
+    const normalized = [];
+    params.value.forEach((value, index) => {
+        const accepted = validateBoundedText({
+            value,
+            maximumLength: params.itemMaximumLength,
+            code: params.code,
+            path: `${params.path}.${index}`,
+            label: params.label,
+            issues: params.issues,
+        });
+        if (accepted !== undefined)
+            normalized.push(accepted);
+    });
+    if (new Set(normalized).size !== normalized.length) {
+        params.issues.push(issue(params.code, params.path, `${params.label} entries must be distinct.`));
+    }
+    return normalized.length === params.value.length
+        ? Object.freeze(normalized)
+        : undefined;
+}
+export function validateBoundedText(params) {
+    const normalized = typeof params.value === "string" ? params.value.trim() : "";
+    const minimumLength = params.minimumLength ?? 1;
+    if (typeof params.value !== "string" ||
+        normalized.length < minimumLength ||
+        params.value.length > params.maximumLength) {
+        params.issues.push(issue(params.code, params.path, `${params.label} must be text of ${minimumLength}-${params.maximumLength} characters.`));
+        return undefined;
+    }
+    return normalized;
+}
+export function readAction(value) {
+    return typeof value === "string" &&
+        EXECUTION_AGENT_DECISION_ACTIONS.includes(value)
+        ? value
+        : undefined;
+}
+export function exactKeys(record, expectedKeys, issues, path) {
+    const expected = new Set(expectedKeys);
+    const actual = Object.keys(record);
+    if (actual.length !== expected.size ||
+        actual.some((key) => !expected.has(key))) {
+        issues.push(issue("execution_agent_decision_shape_invalid", path, "Decision fields must exactly match the selected action."));
+    }
+}
+export function rejectEnvelope(issues) {
+    return {
+        ok: false,
+        stage: "json_envelope",
+        issues: Object.freeze([...issues]),
+    };
+}
+export function issue(code, path, message) {
+    return { code, path, message };
+}
+export function asRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+export function deepFreeze(value, seen = new WeakSet()) {
+    if (typeof value !== "object" || value === null || seen.has(value)) {
+        return value;
+    }
+    seen.add(value);
+    for (const child of Object.values(value)) {
+        deepFreeze(child, seen);
+    }
+    return Object.freeze(value);
+}

package/dist/src/runtime/steps/execution-agent/format.d.ts

@@ -16,6 +16,7 @@ export type PreparedExecutionAgentDecisionContract = Readonly<{
     includeAcknowledgement: boolean;
     includeTitle: boolean;
     allowRespond: boolean;
+    allowMemoryRecall: boolean;
     allowPlanner: boolean;
     allowAuditor: boolean;
     availableAuditCriterionIds: readonly string[];

package/dist/src/runtime/steps/execution-agent/format.js

@@ -1,3 +1,4 @@
+import { createMemoryRecallDecisionSchema } from "../memory-recall-decision.js";
 import { isToolCatalogGroupId } from "../../../capabilities/tool-types.js";
 import { createStructuredDecisionEnvelopeSchema } from "../../model/structured-decision-envelope.js";
 import { CAPABILITY_COUNT_MAX, CAPABILITY_INTENT_MAX_LENGTH, EXECUTION_WORKING_DIRECTORY_MAX_LENGTH, EXECUTION_WORKING_DIRECTORY_PATTERN, canOfferCapabilityBatchSelection, normalizeCapabilityDescriptor, normalizeCapabilityControlsSchema, partitionCapabilityControlsSchema, } from "../../orchestration/capability-adapters/index.js";
@@ -14,6 +15,16 @@ export function createExecutionAgentDecisionFormat(options = {}) {
             selectionSchema: capability.partition.selectionSchema,
         })));
     const variants = [
+        ...(contract.allowMemoryRecall
+            ? [
+                createMemoryRecallDecisionSchema({
+                    includeAcknowledgement: contract.includeAcknowledgement,
+                    includeTitle: contract.includeTitle,
+                    acknowledgementMaxLength: EXECUTION_AGENT_ACKNOWLEDGEMENT_MAX_LENGTH,
+                    titleMaxLength: EXECUTION_AGENT_TITLE_MAX_LENGTH,
+                }),
+            ]
+            : []),
         ...(contract.activeCapabilityCatalogGroupIds === null &&
             contract.capabilityCatalogGroupIds.length > 0
             ? [
@@ -214,6 +225,7 @@ export function prepareExecutionAgentDecisionContract(options) {
         includeAcknowledgement: options.includeAcknowledgement === true,
         includeTitle: options.includeTitle === true,
         allowRespond: options.allowRespond !== false,
+        allowMemoryRecall: options.allowMemoryRecall === true,
         allowPlanner: options.allowPlanner === true,
         allowAuditor: options.allowAuditor === true,
         availableAuditCriterionIds,

package/dist/src/runtime/steps/execution-agent/input.d.ts

@@ -1,4 +1,4 @@
-import type { ModelGatewayJsonSchemaFormat } from "../../../model-gateway/types.js";
+import type { ChatMessage, ModelGatewayJsonSchemaFormat } from "../../../model-gateway/types.js";
 import type { RequestContextProjection } from "../../context/request-context-contracts.js";
 import type { RoleCallFrame, RoleCallLedgerHead } from "../../orchestration/role-calls/index.js";
 import { type CapabilityCatalogGroup, type CapabilityDescriptor } from "../../orchestration/capability-adapters/index.js";
@@ -24,6 +24,7 @@ type BuildExecutionAgentInputOptions = Readonly<{
     includeTitle: boolean;
     allowPlanner: boolean;
     allowAuditor: boolean;
+    memoryRecallMessage?: ChatMessage;
 }>;
 export declare function buildExecutionAgentInput(request: RequestExecutionScope, options: BuildExecutionAgentInputOptions): ExecutionAgentInput;
 export {};

package/dist/src/runtime/steps/execution-agent/input.js

@@ -1,6 +1,9 @@
 import { projectRequestContext } from "../../context/request-context.js";
 import { projectRootSessionMemory } from "../../context/session-memory/root-projection.js";
+import { canOfferMemoryRecall } from "../../long-term-memory/recall-policy.js";
+import { projectMemoryRecallContinuations } from "../../long-term-memory/recall-continuation.js";
 import { buildRequestTemporalContextMessage } from "../../context/request-temporal-context.js";
+import { projectScheduledExecutionContext } from "../../context/scheduled-execution-context.js";
 import { buildImmediateOperationSupervisionEvidenceMessage } from "../../context/operation-supervision-evidence.js";
 import { resolveModelContextBudget } from "../../model/model-context-budget.js";
 import { CAPABILITY_COUNT_MAX, projectCapabilityCatalogGroups, projectCapabilityScope, } from "../../orchestration/capability-adapters/index.js";
@@ -46,7 +49,15 @@ export function buildExecutionAgentInput(request, options) {
     const availableAuditCriterionIds = options.allowAuditor && hasCurrentEvidence
         ? Object.freeze([EXECUTION_AGENT_ROOT_AUDIT_CRITERION_ID])
         : Object.freeze([]);
+    const memoryRecallMessage = request.longTermMemory?.enabled
+        ? options.memoryRecallMessage
+        : undefined;
     const contract = Object.freeze({
+        allowMemoryRecall: canOfferMemoryRecall({
+            enabled: request.longTermMemory?.enabled === true,
+            recallCount: options.head.state.memoryRecalls.length,
+            maxRecallCallsPerRequest: request.memoryRecallLimit,
+        }),
         capabilities,
         capabilityCatalogGroupIds: knownGroupIds,
         activeCapabilityCatalogGroupIds,
@@ -61,6 +72,8 @@ export function buildExecutionAgentInput(request, options) {
     });
     const format = createExecutionAgentDecisionFormat(contract);
     const instructions = buildExecutionAgentInstructions({
+        allowMemoryRecall: contract.allowMemoryRecall,
+        hasMemoryRecallContext: memoryRecallMessage !== undefined,
         hasCapabilities: capabilities.length > 0,
         hasCapabilityCatalogGroups: capabilityCatalogGroups.length > 0,
         capabilityScopeAction,
@@ -71,6 +84,7 @@ export function buildExecutionAgentInput(request, options) {
         includeTitle: options.includeTitle,
         includeWorkingDirectory: options.call.workingDirectory === undefined,
     });
+    const scheduledExecution = projectScheduledExecutionContext(request, instructions, "decision");
     const budget = resolveModelContextBudget({
         runnerConfig: request.runnerConfig,
         agentMode: request.agentMode,
@@ -82,6 +96,7 @@ export function buildExecutionAgentInput(request, options) {
     });
     const operationSupervisionEvidenceMessage = buildImmediateOperationSupervisionEvidenceMessage(options.head, options.call);
     const referenceMessages = [
+        ...scheduledExecution.referenceMessages,
         ...(request.temporalContext
             ? [buildRequestTemporalContextMessage(request.temporalContext)]
             : []),
@@ -94,10 +109,10 @@ export function buildExecutionAgentInput(request, options) {
             ? [buildExecutionCapabilityCatalogMessage(capabilities)]
             : []),
     ];
-    const continuationMessages = buildExecutionContinuationMessages(options.head, options.call);
+    const continuationMessages = buildExecutionContinuationMessages(options.head, options.call, projectMemoryRecallContinuations(memoryRecallMessage));
     const sessionMemory = projectRootSessionMemory(request);
     const context = projectRequestContext({
-        instructions,
+        instructions: scheduledExecution.instructions,
         format,
         ...sessionMemory,
         prompt: request.prompt,

package/dist/src/runtime/steps/execution-agent/parser.d.ts

@@ -1,2 +1 @@
-import { type ExecutionAgentDecisionContractOptions, type ExecutionAgentDecisionParseResult } from "./contracts.js";
-export declare function parseExecutionAgentDecisionOutput(text: string, options?: ExecutionAgentDecisionContractOptions): ExecutionAgentDecisionParseResult;
+export { parseExecutionAgentDecisionOutput } from "./decision-parsing.js";