@memberjunction/ai-agents 6.1.4 → 6.2.0-edge.1

package/dist/base-agent.js

@@ -11,16 +11,17 @@
  * @since 2.49.0
  */
 import { FileStorageEngineBase, MJEnvironmentEntityExtended } from '@memberjunction/core-entities';
-import { buildActionToolSet, filterDeclarableActions, sanitizeToolName } from './native-tools/action-tool-builder.js';
-import { buildNativeToolSet, SUB_AGENT_TOOL_PREFIX } from './native-tools/control-tools.js';
-import { buildAssistantToolCallTurn, buildToolResultTurn, compactToolResultContent } from './native-tools/tool-result-turns.js';
-import { looksLikeLoopEnvelope } from './native-tools/dual-channel.js';
+import { BuildActionToolSet, FilterDeclarableActions, SanitizeToolName } from './native-tools/action-tool-builder.js';
+import { BuildNativeToolSet, SUB_AGENT_TOOL_PREFIX } from './native-tools/control-tools.js';
+import { BuildAssistantToolCallTurn, BuildToolResultTurn, CompactToolResultContent } from './native-tools/tool-result-turns.js';
+import { LooksLikeLoopEnvelope } from './native-tools/dual-channel.js';
+import { ResolvePromptRunUserID } from "@memberjunction/ai-core-plus";
 import { Metadata, RunView, LogStatus, LogStatusEx, LogError, LogErrorEx, IsVerboseLoggingEnabled, DatabaseProviderBase } from '@memberjunction/core';
 import { AgentRunWatchdog } from './agent-run-watchdog.js';
 import { AIPromptRunner, GetToolCallingDecision } from '@memberjunction/ai-prompts';
-import { BaseRealtimeModel, GetAIAPIKey } from '@memberjunction/ai';
+import { BaseRealtimeModel, GetAIAPIKey, IsPrefixPromptCache } from '@memberjunction/ai';
 import { BaseAgentType } from './agent-types/base-agent-type.js';
-import { CopyScalarsAndArrays, JSONValidator, MJGlobal, SafeExpressionEvaluator, UUIDsEqual, EscapeSQLString } from '@memberjunction/global';
+import { CopyScalarsAndArrays, JSONValidator, MJGlobal, NormalizeUUID, SafeExpressionEvaluator, UUIDsEqual, EscapeSQLString } from '@memberjunction/global';
 // token optimization via @memberjunction/context-crush (SmartCrusher/CacheAligner-inspired)
 import { CrushJSON, DescribeCrush, PartitionStablePrefix } from '@memberjunction/context-crush';
 // AST-aware code reduction (CodeCompressor-inspired) — opt-in per agent type
@@ -32,7 +33,7 @@ import { SelectRealtimeVendorForModel } from './realtime/realtime-vendor-resolut
 import { RealtimeClientSessionService, WarnOnUnmatchedProviderVoice } from './realtime/realtime-client-session-service.js';
 import { BuildRealtimeAgentFraming } from './realtime/realtime-tool-broker.js';
 import { RealtimeRecordingController } from './realtime/realtime-recording-capture.js';
-import { resolveRecordingStorageAccountID, storeRealtimeRecording } from './realtime/realtime-recording-store.js';
+import { ResolveRecordingStorageAccountID, StoreRealtimeRecording } from './realtime/realtime-recording-store.js';
 import { AIEngine } from '@memberjunction/aiengine';
 import { ActionEngineServer } from '@memberjunction/actions';
 import { AIAgentPermissionHelper } from '@memberjunction/ai-engine-base';
@@ -43,7 +44,12 @@ import { FormatToolResultSection, FormatToolErrorSection, RenderToolResultData,
 import { PriorTurnToolResultCache } from './prior-turn-tool-result-cache.js';
 import { PromptComponentResolver, InjectScopedPromptParts } from './prompt-component-resolver.js';
 import { ScopedPromptConfigResolver, ApplyScopedPromptConfig } from './scoped-prompt-config-resolver.js';
-import { StringifyForPersistence, AIPromptParams, ChildPromptParam, ConversationUtility, ParseFileOutputRef, parseAssignmentStrategy, ResolveClientTools, initAgentRunStep, finalizeAgentRunStep, AgentRunStepSaveQueue, ExtractPromptResultText, GetTaskGraphSubmitter } from '@memberjunction/ai-core-plus';
+import { StringifyForPersistence, AIPromptParams, ChildPromptParam, ConversationUtility, ParseFileOutputRef, parseAssignmentStrategy, ResolveClientTools, initAgentRunStep, finalizeAgentRunStep, AgentRunStepSaveQueue, ExtractPromptResultText, GetTaskGraphSubmitter, SystemPlaceholderManager } from '@memberjunction/ai-core-plus';
+import { ActionResult, RunActionParams } from '@memberjunction/actions-base';
+import { TemplateEngineServer } from '@memberjunction/templates';
+import { RuntimeStateFragmentBuilder, EscapeRuntimeStateTagsInMessage } from './runtime-state-fragment.js';
+import { ResolveSpecializationPlacement } from './volatile-child-prompt.js';
+import { CURRENT_DATE_PLACEHOLDER, CURRENT_DAY_OF_WEEK_PLACEHOLDER, CURRENT_TIME_PLACEHOLDER, RUNTIME_STATE_TAG, SCRATCHPAD_NOTES_PLACEHOLDER, SCRATCHPAD_TASK_SUMMARY_PLACEHOLDER, SCRATCHPAD_TASKS_PLACEHOLDER, VOLATILE_TEMPLATE_MARKERS, } from './constants.js';
 import { AgentRunner } from './AgentRunner.js';
 import { PayloadManager } from './PayloadManager.js';
 import { ScratchpadManager } from './ScratchpadManager.js';
@@ -106,6 +112,21 @@ import _ from 'lodash';
  * one) from saturating the model API / DB pool with N concurrent runs.
  */
 const PARALLEL_SUBAGENT_CONCURRENCY_LIMIT = 5;
+/** Identical-arguments rule: this many failures with the same arguments block further identical calls. */
+export const IDENTICAL_FAILURE_THRESHOLD = 2;
+/** Attempt budget: this many consecutive failures, across any arguments, disable the action for the run. */
+export const ACTION_FAILURE_BUDGET = 5;
+/**
+ * The {@link ActionResult} returned when the run-scoped circuit breaker blocks a call before it
+ * reaches the action engine. Carries the rule that fired so the failure directive can name it
+ * directly instead of re-deriving it from the failure history, which a blocked call never updates.
+ */
+export class CircuitBreakerActionResult extends ActionResult {
+    constructor(Reason) {
+        super();
+        this.Reason = Reason;
+    }
+}
 export class BaseAgent {
     constructor() {
         /**
@@ -128,6 +149,24 @@ export class BaseAgent {
          * @private
          */
         this._activeProvider = Metadata.Provider; // global-provider-ok: default until Execute() captures per-request provider
+        /**
+         * Index in conversationMessages where this agent run began, used to accurately restore
+         * turn 1's trailing state message in append-only mode without corrupting prior chat turns.
+         * @private
+         */
+        this._turn1InsertionIndex = -1;
+        /**
+         * Actions that have failed fatally (e.g., missing API key, unauthorized, or repeated unrecoverable errors)
+         * during the current agent run. Subsequent attempts to execute these actions are short-circuited in 0ms.
+         * @private
+         */
+        this._fatalActionFailures = new Set();
+        /**
+         * Parameter-aware failure tracking per action name for the current agent run.
+         * Differentiates identical retries (which trip quickly) from parameter modifications (which allow self-correction).
+         * @private
+         */
+        this._actionFailureHistory = new Map();
         /**
          * This is state information that is specific to the agent type. BaseAgent doesn't know what
          * this contains or care, it is just responsible for keeping this, giving the Agent Type the
@@ -460,6 +499,242 @@ export class BaseAgent {
      * @private
      */
     static { this.MAX_CONSECUTIVE_UNPRODUCTIVE_RETRIES = 10; }
+    /**
+     * The identity of one action call's arguments, for the circuit breaker's identical-arguments
+     * rule: two calls with the same normalized string are "the same call", whatever order the model
+     * wrote the keys in.
+     *
+     * Algorithm, top to bottom:
+     * 1. Null, undefined or a non-object yields `''` (a call with no arguments).
+     * 2. The top-level keys are sorted, and each `(key, value)` pair passes through
+     *    {@link normalizeActionParamEntry}, which may rename it, rewrite its value, or drop it.
+     * 3. Every value passes through {@link normalizeActionParamValue}: plain objects are rebuilt with
+     *    sorted keys at EVERY depth, arrays keep their order but normalize each element, and
+     *    anything else (strings, numbers, booleans, null, Dates, entity instances) is kept as is.
+     * 4. The result is serialized with `JSON.stringify`. Should that throw (a circular reference,
+     *    a BigInt), the fallback is a sorted list of the top-level keys — still deterministic, still
+     *    distinguishes differently-shaped calls, and never throws.
+     *
+     * Three protected layers so a subclass can change one part without re-implementing the rest:
+     * override {@link normalizeActionParamEntry} to ignore a key (a trace id, a timestamp the model
+     * regenerates on every call), or {@link normalizeActionParamValue} to canonicalize values
+     * (case-fold a search query, trim whitespace) so near-identical retries count as identical.
+     */
+    normalizeActionParams(params) {
+        if (!params || typeof params !== 'object') {
+            return '';
+        }
+        try {
+            const normalized = {};
+            for (const key of Object.keys(params).sort()) {
+                const entry = this.normalizeActionParamEntry(key, params[key]);
+                if (entry) {
+                    normalized[entry.key] = entry.value;
+                }
+            }
+            return JSON.stringify(normalized);
+        }
+        catch {
+            return `[unserializable:${Object.keys(params).sort().join(',')}]`;
+        }
+    }
+    /**
+     * Normalizes one top-level `(key, value)` pair of an action's arguments. The default keeps the
+     * key and normalizes the value through {@link normalizeActionParamValue}. Return `null` to drop
+     * the pair from the call's identity — the seam for ignoring arguments that legitimately differ
+     * between otherwise identical retries.
+     */
+    normalizeActionParamEntry(key, value) {
+        return { key, value: this.normalizeActionParamValue(value) };
+    }
+    /**
+     * Normalizes one value, recursively: a plain object is rebuilt with its keys sorted, an array
+     * keeps its order with each element normalized, and any other value is returned unchanged. The
+     * seam for canonicalizing values before they are compared.
+     *
+     * "Plain" here is by prototype (`Object.prototype` or none), not the structural
+     * `IsPlainObject` from `@memberjunction/global`: a Date, Map or entity instance must pass through
+     * as an opaque leaf and serialize as itself, not be rebuilt as an empty bag of sorted keys.
+     */
+    normalizeActionParamValue(value) {
+        if (Array.isArray(value)) {
+            return value.map(item => this.normalizeActionParamValue(item));
+        }
+        if (value !== null && typeof value === 'object' && (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null)) {
+            const source = value;
+            const sorted = {};
+            for (const key of Object.keys(source).sort()) {
+                sorted[key] = this.normalizeActionParamValue(source[key]);
+            }
+            return sorted;
+        }
+        return value;
+    }
+    /**
+     * Detects whether an action error message represents a fatal configuration or credential
+     * problem: the tool cannot work in this environment no matter what arguments it is given,
+     * so retrying is pointless and the action is locked out for the rest of the run.
+     *
+     * Deliberately NOT fatal: HTTP 401/403, "unauthorized" and "forbidden". Those are usually
+     * per-resource (one site blocking a fetch, one record the user cannot read) or transient
+     * (a search provider using 403 as a rate limit), so they fall through to the parameter-aware
+     * failure history where the identical-arguments rule and the consecutive-attempt budget
+     * bound them without disabling the tool for every other resource.
+     *
+     * Also NOT fatal, for the same reason: a failure the model can fix by changing its arguments.
+     * A message that names a parameter is treated as an argument problem whatever else it says,
+     * and a call that itself carried credential-shaped arguments (password, API key, token) is
+     * never fatal even on "authentication failed", because the credential came from the model,
+     * not the environment. Demoting a message from fatal costs at most the attempt budget.
+     *
+     * @param message The action's failure message.
+     * @param actionParams The arguments the call was made with, when known.
+     */
+    isFatalActionError(message, actionParams) {
+        if (!message) {
+            return false;
+        }
+        // 1. Parameter/argument/input problems are recoverable (the agent can adjust inputs), so they
+        // never trip the fatal breaker, however the rest of the message is phrased.
+        const isParamError = /\b(?:parameter|argument|param|input|field|option|property|value|column|filter|header)\b/i.test(message);
+        if (isParamError || this.hasCredentialShapedArguments(actionParams)) {
+            return false;
+        }
+        // 2. Missing or invalid credentials, API keys, or authentication failures are unrecoverable in this run
+        const fatalCredentialPattern = /(?:api[\s_-]?key\s+(?:is\s+)?(?:not\s+found|missing|required|invalid)|(?:missing|invalid)\s+api[\s_-]?key|no\s+api[\s_-]?key|credentials?\s+(?:not\s+found|missing)|authentication\s+failed)/i;
+        if (fatalCredentialPattern.test(message)) {
+            return true;
+        }
+        // 3. Action/service/provider-level configuration problems where the tool itself cannot execute in this environment
+        const fatalConfigPattern = /(?:(?:action|tool|service|provider|integration|driver|client|api|extension|engine|server)\s+(?:is\s+)?not\s+configured|not\s+configured\s+(?:for\s+(?:this\s+)?tenant|in\s+(?:this\s+)?environment|on\s+this\s+server|in\s+(?:config|mj\.config))|^\s*(?:action\s+)?(?:is\s+)?not\s+configured[.!]*\s*$)/i;
+        return fatalConfigPattern.test(message);
+    }
+    /**
+     * True when any top-level argument name looks like a credential the model supplied itself
+     * (password, secret, credential, API key, or an access / auth / bearer / refresh / ID token).
+     * `maxTokens`-style names are deliberately not matched.
+     */
+    hasCredentialShapedArguments(actionParams) {
+        if (!actionParams || typeof actionParams !== 'object') {
+            return false;
+        }
+        const credentialKey = /password|passwd|secret|credential|api[_-]?key|(?:access|auth|bearer|refresh|id)[_-]?token|^token$/i;
+        return Object.keys(actionParams).some(key => credentialKey.test(key));
+    }
+    /**
+     * Records a non-successful outcome for the run-scoped action circuit breaker. A fatal
+     * configuration error locks the action out for the rest of the run; any other failure
+     * updates the parameter-aware history behind the identical-arguments rule and the
+     * consecutive-attempt budget.
+     */
+    recordActionFailure(action, actionEntity, message, normalizedParams) {
+        if (this.isFatalActionError(message, action.params)) {
+            this._fatalActionFailures.add(action.name);
+            if (actionEntity?.Name) {
+                this._fatalActionFailures.add(actionEntity.Name);
+            }
+            return;
+        }
+        const existing = this._actionFailureHistory.get(action.name) || (actionEntity?.Name ? this._actionFailureHistory.get(actionEntity.Name) : undefined);
+        const isIdentical = existing !== undefined && existing.lastParamsString === normalizedParams;
+        const record = {
+            lastParamsString: normalizedParams,
+            identicalFailures: isIdentical && existing ? existing.identicalFailures + 1 : 1,
+            totalConsecutiveFailures: (existing?.totalConsecutiveFailures ?? 0) + 1
+        };
+        this._actionFailureHistory.set(action.name, record);
+        if (actionEntity?.Name) {
+            this._actionFailureHistory.set(actionEntity.Name, record);
+        }
+    }
+    /**
+     * Clears the parameter-aware failure history for an action after it succeeds, so the
+     * identical-arguments rule and the consecutive-attempt budget start over.
+     */
+    clearActionFailureRecord(action, actionEntity) {
+        this._actionFailureHistory.delete(action.name);
+        if (actionEntity?.Name) {
+            this._actionFailureHistory.delete(actionEntity.Name);
+        }
+    }
+    /**
+     * Applies the three circuit-breaker rules to a call that is about to be dispatched. Returns a
+     * blocked result, with the rule that fired, when the call must not go to the action engine;
+     * null when it may proceed. Rules are checked fatal → identical-arguments → budget.
+     */
+    checkActionCircuitBreaker(params, action, actionEntity, normalizedParams) {
+        const entityKey = actionEntity?.Name;
+        if (this._fatalActionFailures.has(action.name) || (entityKey && this._fatalActionFailures.has(entityKey))) {
+            this.logStatus(`   ⚡ Circuit breaker: Action '${action.name}' short-circuited (0ms): fatal configuration or credential error earlier in this run`, false, params);
+            return this.buildBlockedActionResult(actionEntity, 'fatal', `Action '${action.name}' is disabled for this run because it previously failed with an unrecoverable configuration or credential error. You must select an alternative action.`);
+        }
+        const record = this._actionFailureHistory.get(action.name) || (entityKey ? this._actionFailureHistory.get(entityKey) : undefined);
+        if (!record) {
+            return null;
+        }
+        if (record.lastParamsString === normalizedParams && record.identicalFailures >= IDENTICAL_FAILURE_THRESHOLD) {
+            this.logStatus(`   ⚡ Circuit breaker: Action '${action.name}' short-circuited on identical retry loop (0ms)`, false, params);
+            return this.buildBlockedActionResult(actionEntity, 'identical-arguments', `Action '${action.name}' is disabled for these inputs because it already failed ${record.identicalFailures} times with identical arguments. You must modify your parameters or select an alternative tool.`);
+        }
+        if (record.totalConsecutiveFailures >= ACTION_FAILURE_BUDGET) {
+            this.logStatus(`   ⚡ Circuit breaker: Action '${action.name}' short-circuited on max retry attempts (0ms)`, false, params);
+            return this.buildBlockedActionResult(actionEntity, 'attempts-exhausted', `Action '${action.name}' is disabled for this run after ${ACTION_FAILURE_BUDGET} consecutive failures across parameter attempts. You must select an alternative tool or proceed with available data.`);
+        }
+        return null;
+    }
+    /** The failed {@link ActionResult} a blocked call returns in place of dispatching. */
+    buildBlockedActionResult(actionEntity, reason, message) {
+        const blocked = new CircuitBreakerActionResult(reason);
+        blocked.Success = false;
+        blocked.Message = message;
+        blocked.Params = [];
+        blocked.RunParams = new RunActionParams();
+        blocked.RunParams.Action = actionEntity;
+        return blocked;
+    }
+    /**
+     * Names the rule behind a failed action summary so the directive matches what actually
+     * happened. A blocked call reports the rule that blocked it. A dispatched failure is fatal if
+     * `recordActionFailure` locked the action out (the summary has no access to the call's
+     * arguments, so the decision is read back rather than re-derived from the message); otherwise
+     * the budget is checked BEFORE the identical-arguments rule, because once the budget is spent
+     * the action is blocked whatever the arguments are, and telling the model to change them
+     * would send it in circles.
+     */
+    classifyActionFailure(summary) {
+        if (summary.breakerReason) {
+            return summary.breakerReason;
+        }
+        if (this._fatalActionFailures.has(summary.actionName)) {
+            return 'fatal';
+        }
+        const record = this._actionFailureHistory.get(summary.actionName);
+        if (!record) {
+            return 'warning';
+        }
+        if (record.totalConsecutiveFailures >= ACTION_FAILURE_BUDGET) {
+            return 'attempts-exhausted';
+        }
+        if (record.identicalFailures >= IDENTICAL_FAILURE_THRESHOLD) {
+            return 'identical-arguments';
+        }
+        return 'warning';
+    }
+    /** The guidance line appended to the history for one failed action. */
+    formatActionFailureDirective(summary) {
+        const name = summary.actionName;
+        const record = this._actionFailureHistory.get(name);
+        switch (this.classifyActionFailure(summary)) {
+            case 'fatal':
+                return `[CRITICAL/ACTION_UNAVAILABLE] Action '${name}' failed with an unrecoverable configuration or credential error: "${summary.message}". This action cannot execute in this environment. DO NOT call '${name}' again during this run. You MUST select an alternative tool or proceed with available data.`;
+            case 'attempts-exhausted':
+                return `[CRITICAL/ATTEMPTS_EXHAUSTED] Action '${name}' has failed ${record?.totalConsecutiveFailures ?? ACTION_FAILURE_BUDGET} consecutive times: "${summary.message}". Retries for this action are exhausted. You MUST pivot to an alternative tool or continue with available data.`;
+            case 'identical-arguments':
+                return `[CRITICAL/REPEATED_IDENTICAL_CALL] Action '${name}' failed again with the EXACT SAME arguments: "${summary.message}". Calling '${name}' with these parameters will not work. You MUST either adjust your parameters or pivot to an alternative tool.`;
+            default:
+                return `[WARNING/ACTION_FAILURE] Action '${name}' failed: "${summary.message}". Review the error and adjust your input parameters (attempt ${record?.totalConsecutiveFailures ?? 1} of ${ACTION_FAILURE_BUDGET}). DO NOT retry calling '${name}' with identical arguments.`;
+        }
+    }
     /**
      * Returns the active metadata provider for this agent run. Subclasses MUST
      * use this getter (rather than `new Metadata()` or `Metadata.Provider`) so
@@ -575,12 +850,16 @@ export class BaseAgent {
      * }]);
      * ```
      */
-    promoteMediaOutputs(mediaOutputs) {
+    PromoteMediaOutputs(mediaOutputs) {
         if (mediaOutputs && mediaOutputs.length > 0) {
             this._mediaOutputs.push(...mediaOutputs);
             this.logStatus(`📎 Promoted ${mediaOutputs.length} media output(s) to agent results`, true);
         }
     }
+    /** @deprecated Use {@link PromoteMediaOutputs}. */
+    promoteMediaOutputs(mediaOutputs) {
+        return this.PromoteMediaOutputs(mediaOutputs);
+    }
     /**
      * Gets the currently accumulated media outputs for this agent run.
      * @returns Array of promoted media outputs
@@ -1196,6 +1475,11 @@ export class BaseAgent {
             this._executeParams = wrappedParams;
             this._agentConfig = undefined;
             this._lastModelSelectionInfo = undefined;
+            this._lastVolatileStateMessage = undefined;
+            this._resolvedTrailingStateMode = undefined;
+            this._turn1InsertionIndex = -1;
+            this._fatalActionFailures.clear();
+            this._actionFailureHistory.clear();
             // Convert UI markup in conversation messages to plain text if requested (default: true)
             if (params.convertUIMarkupToPlainText !== false) {
                 this.convertUIMarkupInMessages(wrappedParams.conversationMessages);
@@ -1206,7 +1490,8 @@ export class BaseAgent {
             this._memoryWriteManager.Clear();
             // Arm conversation-history retrieval tools — available only when the run has a
             // conversation to page against (the same gate as all cross-turn context features).
-            this._conversationToolManager.Initialize(wrappedParams.conversationId || null, params.contextUser);
+            // A history floor holds here too: the tools page only rows from it onward.
+            this._conversationToolManager.Initialize(wrappedParams.conversationId || null, params.contextUser, wrappedParams.ConversationHistoryFrom ?? null);
             this._conversationToolManager.SetSummaryHost(this.buildConversationSummaryHost(wrappedParams));
             // Initialize artifact tools with any input artifacts attached to the run.
             // Artifacts arrive as a typed first-class field on ExecuteAgentParams —
@@ -1753,6 +2038,11 @@ export class BaseAgent {
             promptRun.ModelID = modelResolution.modelID;
             promptRun.VendorID = modelResolution.vendorID || null;
             promptRun.AgentID = params.agent.ID;
+            promptRun.UserID = ResolvePromptRunUserID({
+                UserID: params.userId,
+                AgentRun: this._agentRun,
+                ContextUser: params.contextUser,
+            });
             promptRun.Status = 'Running';
             promptRun.RunAt = new Date();
             promptRun.StreamingEnabled = true;
@@ -2260,7 +2550,7 @@ export class BaseAgent {
             }
             // Storage: recording provider, else attachment provider; then that provider's first account.
             const storageAccountId = params.contextUser
-                ? await resolveRecordingStorageAccountID(agent, params.contextUser, params.provider || this._activeProvider)
+                ? await ResolveRecordingStorageAccountID(agent, params.contextUser, params.provider || this._activeProvider)
                 : null;
             if (!storageAccountId) {
                 this.logStatus('🔴 Realtime recording on but no resolvable storage account (RecordingStorageProviderID/AttachmentStorageProviderID) — recording disabled.', false, params);
@@ -2311,7 +2601,7 @@ export class BaseAgent {
             // same mixed PCM as the WAV — persisted as a peaks.json sidecar so the player renders the
             // real waveform without re-decoding the audio. Best-effort: an empty array writes no sidecar.
             const peaks = controller.GetPeaks();
-            const stored = await storeRealtimeRecording({
+            const stored = await StoreRealtimeRecording({
                 Audio: encoded.Buffer,
                 MimeType: 'audio/wav',
                 Media: controller.Media,
@@ -2451,7 +2741,7 @@ export class BaseAgent {
             stepCount++;
             // Promote any media outputs from this step to the agent's outputs
             if (nextStep.promoteMediaOutputs && nextStep.promoteMediaOutputs.length > 0) {
-                this.promoteMediaOutputs(nextStep.promoteMediaOutputs);
+                this.PromoteMediaOutputs(nextStep.promoteMediaOutputs);
             }
             // Track consecutive failed steps to prevent infinite retry loops.
             // Any non-Failed step resets the counter.
@@ -2976,7 +3266,7 @@ export class BaseAgent {
                 stepEntity.NativeToolCallCount = callCount;
                 // A tool call wins, but a turn that ALSO carried a valid
                 // envelope gave two answers, and the one we discard has to be counted somewhere.
-                stepEntity.NativeDualChannel = callCount > 0 ? looksLikeLoopEnvelope(message?.content) : null;
+                stepEntity.NativeDualChannel = callCount > 0 ? LooksLikeLoopEnvelope(message?.content) : null;
                 // whether this step's results went back as native tool-result turns.
                 stepEntity.NativeToolResultsSent = GetToolCallingDecision(promptResult?.chatResult)?.toolResults === true;
                 if (stepEntity.NativeDualChannel) {
@@ -3006,7 +3296,7 @@ export class BaseAgent {
         if (!turn?.sendResultsNatively || this._lastNativeTurnAppended === turn) {
             return;
         }
-        params.conversationMessages.push(buildAssistantToolCallTurn(turn));
+        params.conversationMessages.push(BuildAssistantToolCallTurn(turn));
         this._lastNativeTurnAppended = turn;
     }
     /**
@@ -3051,13 +3341,13 @@ export class BaseAgent {
             }
             results.push({
                 toolCallId: action.toolCallId,
-                toolName: sanitizeToolName(summary.actionName),
+                toolName: SanitizeToolName(summary.actionName),
                 content: this.formatActionResultsAsMarkdown([summary]),
                 isError: !summary.success
             });
         }
         if (results.length > 0) {
-            params.conversationMessages.push(buildToolResultTurn(results, metadata));
+            params.conversationMessages.push(BuildToolResultTurn(results, metadata));
         }
         if (orphans.length > 0) {
             params.conversationMessages.push({ role: 'user', content: `Action results:\n${this.formatActionResultsAsMarkdown(orphans)}`, metadata });
@@ -3117,7 +3407,7 @@ export class BaseAgent {
         if (unanswered.length === 0) {
             return;
         }
-        params.conversationMessages.push(buildToolResultTurn(unanswered.map((call) => ({
+        params.conversationMessages.push(BuildToolResultTurn(unanswered.map((call) => ({
             toolCallId: call.id,
             toolName: call.name,
             content: 'Not executed — the agent did not run this call on this turn. See the message that follows.',
@@ -3129,7 +3419,7 @@ export class BaseAgent {
      * answers, which every provider rejects. Expiry and recovery stub its blocks instead.
      */
     stubToolTurn(message, note) {
-        return compactToolResultContent(message, () => note);
+        return CompactToolResultContent(message, () => note);
     }
     applyNativeTools(promptParams, params) {
         this._nativeToolBindings = undefined;
@@ -3147,18 +3437,18 @@ export class BaseAgent {
             return;
         }
         // ...and a per-agent-ACTION gate: rows that opt out are removed before the tool set is built.
-        const actions = filterDeclarableActions(this.getEffectiveActionsForValidation(params.agent.ID), AIEngine.Instance.AgentActions.filter((aa) => UUIDsEqual(aa.AgentID, params.agent.ID)));
+        const actions = FilterDeclarableActions(this.getEffectiveActionsForValidation(params.agent.ID), AIEngine.Instance.AgentActions.filter((aa) => UUIDsEqual(aa.AgentID, params.agent.ID)));
         const subAgents = this.getEffectiveSubAgentsForValidation(params.agent.ID);
         if (actions.length === 0 && subAgents.length === 0) {
             return;
         }
         try {
-            const actionSet = buildActionToolSet(actions, new Map(actions.map((a) => [a.ID, a.Params.Items])));
+            const actionSet = BuildActionToolSet(actions, new Map(actions.map((a) => [a.ID, a.Params.Items])));
             // Under implicit control flow the agent cannot know which model will answer, so it declares the full
             // set — Actions plus the control-flow tools (one per sub-agent, payload_change_request,
             // ask_user) — and NAMES the control ones. The runner keeps them only when the selected
             // model's LLM.NativeControlFlow resolves to 'implicit'; a hybrid model never sees them.
-            const toolSet = buildNativeToolSet(actionSet, subAgents);
+            const toolSet = BuildNativeToolSet(actionSet, subAgents);
             promptParams.tools = toolSet.tools;
             promptParams.controlFlowToolNames = toolSet.controlToolNames;
             promptParams.toolChoice = this.resolveToolChoiceForTurn(params);
@@ -3239,6 +3529,11 @@ export class BaseAgent {
         // Attribute the resulting AIPromptRun to this agent. Agents share agent-type-level system
         // prompts, so without this a parent's inference and its sub-agent's are indistinguishable.
         promptParams.agentId = params.agent.ID;
+        promptParams.UserID = ResolvePromptRunUserID({
+            UserID: params.userId,
+            AgentRun: this._agentRun,
+            ContextUser: params.contextUser,
+        }) ?? undefined;
         // Handle case where systemPrompt is optional (e.g., Flow Agent Type)
         if (systemPrompt) {
             promptParams.prompt = systemPrompt;
@@ -3294,9 +3589,9 @@ export class BaseAgent {
             const agentTypePromptParams = promptParams.data.__agentTypePromptParams;
             const scratchpadEnabled = agentTypePromptParams?.includeScratchpadDocs !== false;
             if (scratchpadEnabled && this._scratchpadManager) {
-                promptParams.data['_SCRATCHPAD_NOTES'] = this._scratchpadManager.GetNotes() || '_(no notes yet)_';
-                promptParams.data['_SCRATCHPAD_TASKS'] = this._scratchpadManager.ToPromptString();
-                promptParams.data['_SCRATCHPAD_TASK_SUMMARY'] = this._scratchpadManager.GetTaskSummary();
+                promptParams.data[SCRATCHPAD_NOTES_PLACEHOLDER] = this._scratchpadManager.GetNotes() || '_(no notes yet)_';
+                promptParams.data[SCRATCHPAD_TASKS_PLACEHOLDER] = this._scratchpadManager.ToPromptString();
+                promptParams.data[SCRATCHPAD_TASK_SUMMARY_PLACEHOLDER] = this._scratchpadManager.GetTaskSummary();
             }
             // Inject artifact tools template variables if enabled and artifacts are present.
             // Note: prior tool results are NO LONGER injected via a per-turn template var.
@@ -3432,8 +3727,334 @@ export class BaseAgent {
                     params.data?.SecondaryScopes,
             }, promptParams);
         }
+        // Prompt-cache layout. The per-iteration state (and, when the child prompt is volatile, the
+        // specialization) never lives in the system prompt; it rides as the FINAL message of THIS request.
+        // In append-only mode (OpenAI prompt caching), prior runtime-state fragments are retained in history
+        // so each turn extends the exact byte prefix of the previous request, maintaining ~93% cache hits.
+        // In replace-in-place mode (Gemini/Cerebras), only the latest fragment is attached, keeping history lean.
+        const volatileStateMessage = await this.buildVolatileStateMessage(params, promptParams, payload, childPrompt, agentType, systemPrompt);
+        if (volatileStateMessage) {
+            const isAppendOnly = this.shouldUseAppendOnlyTrailingState(promptParams);
+            this.restoreTurn1VolatileStateIfNeeded(params, isAppendOnly);
+            promptParams.conversationMessages = this.assembleOutgoingMessages(params.conversationMessages, volatileStateMessage, isAppendOnly);
+            if (isAppendOnly) {
+                params.conversationMessages.push(volatileStateMessage);
+            }
+            this._lastVolatileStateMessage = volatileStateMessage;
+        }
         return promptParams;
     }
+    /**
+     * In append-only mode, restores turn 1's volatile state fragment if mode resolution
+     * was deferred until after turn 1 (e.g. dynamic model selection).
+     *
+     * Restores the fragment at the exact message boundary where turn 1 executed, ensuring
+     * earlier turns in multi-turn conversations are not corrupted.
+     *
+     * This is only correct for a replace → append-only flip between turn 1 and turn 2, when
+     * `_lastVolatileStateMessage` still holds turn 1's fragment. `shouldUseAppendOnlyTrailingState`
+     * freezes the mode at the first model selection precisely so that no later flip can occur.
+     */
+    restoreTurn1VolatileStateIfNeeded(params, isAppendOnly) {
+        if (this._turn1InsertionIndex < 0) {
+            // Record the message boundary at Turn 1 before any loop messages are added
+            this._turn1InsertionIndex = params.conversationMessages.length;
+        }
+        else if (isAppendOnly && this._lastVolatileStateMessage && !this.runHasVolatileStateMessage(params)) {
+            // If append-only was resolved after turn 1 (via _lastModelSelectionInfo),
+            // restore turn 1's fragment at the exact position where turn 1 executed it (the turn 1 boundary)
+            // to ensure exact prefix match without corrupting pre-existing conversation history.
+            const insertIdx = Math.min(this._turn1InsertionIndex, params.conversationMessages.length);
+            params.conversationMessages.splice(insertIdx, 0, this._lastVolatileStateMessage);
+        }
+    }
+    /**
+     * Whether THIS run has already placed a volatile-state fragment in the history, i.e. at or after
+     * the turn-1 boundary. Fragments before the boundary belong to an earlier run whose history the
+     * caller reused; they must not suppress this run's turn-1 restore.
+     */
+    runHasVolatileStateMessage(params) {
+        const start = Math.max(0, this._turn1InsertionIndex);
+        return params.conversationMessages.slice(start).some(m => m.metadata?.volatileState === true);
+    }
+    /**
+     * The message array sent for ONE request under `'trailingMessage'` placement: a copy of the history
+     * with every non-system message's fragment tag literals escaped, then the real fragment last.
+     *
+     * Escaping at send time (rather than where text enters the history) covers every source at once —
+     * user turns, action results, sub-agent results, skill activations — without rewriting stored data,
+     * and it is deterministic, so the cached prefix stays byte-stable across iterations. System messages
+     * and framework-authored volatile state messages are left alone.
+     */
+    assembleOutgoingMessages(history, fragment, isAppendOnly = false) {
+        const source = isAppendOnly ? history : history.filter(m => !m.metadata?.volatileState);
+        const sanitized = source.map(m => (m.role === 'system' || m.metadata?.volatileState ? m : EscapeRuntimeStateTagsInMessage(m)));
+        return [...sanitized, fragment];
+    }
+    /**
+     * Determines whether the current prompt execution should use append-only trailing state retention.
+     *
+     * Why: OpenAI and xAI prompt caching operate on an exact byte prefix match from token 0. Replacing the
+     * trailing runtime-state fragment turn-over-turn breaks the byte prefix after the system prompt,
+     * dropping cache hit rates significantly. In append-only mode, prior runtime state messages are
+     * retained in the message history so each turn is an exact prefix extension of the prior turn,
+     * achieving ~93% cache hit rate. Providers with block-level or sliding caching (Gemini, Cerebras)
+     * use replace-in-place to keep context compact.
+     *
+     * Which providers are which is METADATA, not code: the `PrefixPromptCache` flag in the model
+     * catalog's `ModelConfiguration` cascade (Model Types < Models < Vendors' `Configuration.ModelDefaults`
+     * < Model Vendors), read through {@link resolvePrefixPromptCache}. `true` means append-only;
+     * anything else means replace.
+     *
+     * Decided ONCE per run. An explicit `trailingStateMode` or a runtime model override answers
+     * immediately. Otherwise the answer is frozen at the first model selection and reused for every
+     * later turn, so a failover to another vendor cannot flip the layout mid-run — a flip after turn 2
+     * would leave stale fragments in the history or, worse, restore the wrong turn's fragment. On turn 1,
+     * before any selection is known, the answer is replace-in-place: turn 1's fragment is kept and, if
+     * turn 2 resolves to append-only, spliced back at the turn-1 boundary, which reproduces exactly the
+     * bytes an append-only turn 1 would have sent. Nothing is lost by deferring, so the prompt's bound
+     * models are deliberately NOT consulted — prompts commonly bind several vendors for failover, and
+     * guessing from them mis-pins runs that end up selecting another vendor.
+     */
+    shouldUseAppendOnlyTrailingState(promptParams) {
+        const data = promptParams.data ?? {};
+        // An explicit trailingStateMode wins; 'auto' (the default) or an absent key falls through to
+        // vendor/model detection below. See TrailingStateMode for when to force either mode.
+        const agentTypePromptParams = data.__agentTypePromptParams;
+        if (agentTypePromptParams?.trailingStateMode === 'appendOnly') {
+            return true;
+        }
+        if (agentTypePromptParams?.trailingStateMode === 'replace') {
+            return false;
+        }
+        // A model override pins the serving path for the whole run, so it answers now. A vendor-only
+        // override cannot: the strategy lives on the model-vendor row, which needs the model too, so
+        // that case is decided at the first selection like any other run.
+        if (promptParams.override?.modelId) {
+            const model = AIEngine.Instance?.ModelsByID?.get(NormalizeUUID(promptParams.override.modelId));
+            const vendor = promptParams.override.vendorId ? AIEngine.Instance?.VendorsByID?.get(NormalizeUUID(promptParams.override.vendorId)) : undefined;
+            return this.resolvePrefixPromptCache(model, vendor);
+        }
+        if (this._resolvedTrailingStateMode !== undefined) {
+            return this._resolvedTrailingStateMode;
+        }
+        if (this._lastModelSelectionInfo) {
+            const model = this._lastModelSelectionInfo.ModelSelected;
+            const vendor = this._lastModelSelectionInfo.vendorSelected;
+            this._resolvedTrailingStateMode = this.resolvePrefixPromptCache(model, vendor);
+            return this._resolvedTrailingStateMode;
+        }
+        // Turn 1, nothing known yet: replace-in-place, resolved for good on turn 2 (see above).
+        return false;
+    }
+    /**
+     * Whether a model, as served by a vendor, sits behind a byte-prefix prompt cache
+     * (`LLM.PrefixPromptCache`), read from the model catalog's `ModelConfiguration` cascade —
+     * `AIModelType < AIModel < AIVendor.Configuration.ModelDefaults < AIModelVendor` — via
+     * `AIEngine.GetEffectiveModelConfiguration`. The most specific layer is the INFERENCE-PROVIDER
+     * model-vendor row for `vendor`, whose vendor row supplies the host-wide default that beats the
+     * model's own bag; when the vendor is unknown, or has no inference row for this model, the model
+     * and type layers still answer. False when no layer declares it, which callers
+     * treat as a block cache (replace-in-place).
+     *
+     * Extension point: a subclass with out-of-catalog knowledge (an OpenAI-compatible gateway whose
+     * rows carry no flag, say) can override this rather than the mode decision above.
+     */
+    resolvePrefixPromptCache(model, vendor) {
+        if (!model) {
+            return false;
+        }
+        const engine = AIEngine.Instance;
+        const modelVendor = vendor
+            ? (engine.ModelVendorsByModelID?.get(NormalizeUUID(model.ID)) ?? []).find(mv => UUIDsEqual(mv.VendorID, vendor.ID) && engine.IsInferenceProvider(mv))
+            : undefined;
+        return IsPrefixPromptCache(engine.GetEffectiveModelConfiguration(model.ID, modelVendor?.ID));
+    }
+    /**
+     * Builds the framework-authored `user` message that carries the loop agent's volatile state as the
+     * final message of the request; returns null only when every block is turned off, or when the
+     * system prompt template in this database has not yet synced and still embeds the state itself
+     * (see the guard below). The blocks mirror the sections the template used to render (see
+     * {@link RuntimeStateFragmentBuilder}), and each honors the same include flag the template did.
+     *
+     * Why this exists: provider prompt caching is a prefix match over tools → system → messages, so
+     * state that changes every iteration INSIDE the system prompt invalidates the entire history each
+     * call. Measured on Sage: 36% → 83% cached on Gemini 2.5 Flash, 12% → 96% on Claude Opus 5 (with the
+     * Anthropic adapter placing its breakpoint before this message), output quality unchanged.
+     *
+     * The message carries STATE only — never rules. It is marked `metadata.volatileState` so adapters
+     * can recognize it without depending on this package's tag names.
+     */
+    async buildVolatileStateMessage(params, promptParams, payload, childPrompt, agentType, systemPrompt) {
+        const data = promptParams.data ?? {};
+        const agentTypePromptParams = data.__agentTypePromptParams;
+        // Delivery gate: the fragment is emitted only for a system prompt whose template points the model
+        // at it. See resolveRuntimeStateDelivery for the two ways a template can fail that test.
+        const effectiveSystemPrompt = systemPrompt ?? promptParams.prompt;
+        const delivery = await this.resolveRuntimeStateDelivery(effectiveSystemPrompt, params.contextUser);
+        if (delivery === 'embedded') {
+            this.logStatus('⚠️ System prompt template still contains volatile blocks (database template unsynced); skipping trailing runtime-state fragment to avoid duplicate state.', true, params);
+            return null;
+        }
+        if (delivery === 'unsupported') {
+            this.logStatus(`System prompt template has no <${RUNTIME_STATE_TAG}> pointer (not a Loop agent system prompt); skipping trailing runtime-state fragment.`, true, params);
+            return null;
+        }
+        const includeDateTime = agentTypePromptParams?.includeDateTimeInPrompt !== false;
+        const includeScratchpad = agentTypePromptParams?.includeScratchpadDocs !== false;
+        const includePayload = agentTypePromptParams?.includePayloadInPrompt !== false;
+        const specialization = await this.resolveRelocatedSpecialization(promptParams, childPrompt, agentType, params.contextUser);
+        const fragment = new RuntimeStateFragmentBuilder().Build({
+            DateTime: includeDateTime ? await this.resolveFragmentDateTime(promptParams) : null,
+            Scratchpad: includeScratchpad ? this.readScratchpadFromTemplateData(data) : null,
+            // Same value the agent type injects for the template (`payload || {}`), so both placements agree.
+            Payload: includePayload ? { Value: payload || {} } : null,
+            Specialization: specialization,
+        });
+        if (!fragment) {
+            return null;
+        }
+        this.logStatus(`📦 Volatile state → trailing message (${fragment.length} chars${specialization ? ', specialization relocated' : ''})`, true, params);
+        return { role: 'user', content: fragment, metadata: { volatileState: true, turnAdded: this._promptTurnCount } };
+    }
+    /**
+     * Decides whether this run's specialization (child prompt) rides in the trailing message, and if so
+     * pre-renders it and flags the template to render a stub in its place. Decided from the child
+     * template's UNRENDERED text via {@link ResolveSpecializationPlacement}, so the answer is the same on
+     * every iteration and the layout never flips mid-run. Returns the rendered specialization, or null
+     * when it stays in the system prompt.
+     */
+    async resolveRelocatedSpecialization(promptParams, childPrompt, agentType, contextUser) {
+        const placeholder = agentType.AgentPromptPlaceholder;
+        if (!childPrompt || !placeholder || !promptParams.childPrompts || promptParams.childPrompts.length === 0) {
+            return null;
+        }
+        const templateText = await this.loadChildPromptTemplateText(childPrompt, contextUser);
+        const agentTypePromptParams = promptParams.data?.__agentTypePromptParams;
+        if (ResolveSpecializationPlacement(agentTypePromptParams, templateText) !== 'trailingMessage') {
+            return null;
+        }
+        const rendered = await this._promptRunner.RenderChildPromptTemplates(promptParams.childPrompts, promptParams);
+        const text = rendered.renderedTemplates[placeholder];
+        if (!text || text.trim().length === 0) {
+            return null;
+        }
+        // Cache pre-rendered child templates so AIPromptRunner.ExecutePrompt does not re-render them
+        promptParams.PreRenderedChildTemplates = rendered.renderedTemplates;
+        // The same data object the parent template renders against — this switches the `## Specialization`
+        // block to its stub and extends the Runtime State pointer.
+        if (promptParams.data) {
+            promptParams.data._SPECIALIZATION_RELOCATED = true;
+        }
+        return text;
+    }
+    /**
+     * Decides, from the system prompt's UNRENDERED template text, whether the trailing runtime-state
+     * fragment belongs on this request:
+     *
+     * - `'trailing'` — the template carries the `<mj-runtime-state>` pointer, so the model is told where
+     *   the state lives. The Loop agent system prompt.
+     * - `'embedded'` — the template still renders the state blocks itself (an environment whose
+     *   TemplateContent has not synced the new Loop template, or the Flow template, which embeds the
+     *   payload). Emitting the fragment would deliver the same state twice.
+     * - `'unsupported'` — the template has neither. The Harness system prompt, or a custom prompt run
+     *   without the Loop system prompt. The model would receive an unexplained block.
+     * - `'unknown'` — no template text to inspect (no TemplateID, or the lookup failed). The caller
+     *   fails OPEN here: a Loop agent losing its payload from the model's view is far worse than a
+     *   non-Loop agent receiving an unexplained fragment, and in practice every agent type's system
+     *   prompt has a template, so this arises only from a lookup failure.
+     */
+    async resolveRuntimeStateDelivery(systemPrompt, contextUser) {
+        const templateText = await this.loadPromptTemplateText(systemPrompt, contextUser);
+        if (templateText === null) {
+            return 'unknown';
+        }
+        if (this.templateTextEmbedsVolatileState(templateText)) {
+            return 'embedded';
+        }
+        return templateText.includes(`<${RUNTIME_STATE_TAG}>`) ? 'trailing' : 'unsupported';
+    }
+    /**
+     * The strings whose presence in a system prompt's unrendered template text means the template
+     * still renders the volatile state itself, so the trailing fragment must be suppressed. Defaults
+     * to {@link VOLATILE_TEMPLATE_MARKERS}: the three block headings plus the date and payload
+     * placeholders. Extension point — an agent type whose template lays the state out under other
+     * headings overrides this to return its own markers.
+     */
+    get volatileTemplateMarkers() {
+        return VOLATILE_TEMPLATE_MARKERS;
+    }
+    /**
+     * True when unrendered template text contains any of {@link volatileTemplateMarkers} — the legacy
+     * Loop layout, or any template that embeds the payload.
+     */
+    templateTextEmbedsVolatileState(templateText) {
+        return this.volatileTemplateMarkers.some(marker => templateText.includes(marker));
+    }
+    /**
+     * Raw template text (placeholders intact) for an AI prompt from the cached template engine.
+     * Null when the prompt has no template or the lookup fails.
+     */
+    async loadPromptTemplateText(prompt, contextUser) {
+        if (!prompt?.TemplateID) {
+            return null;
+        }
+        try {
+            await TemplateEngineServer.Instance.Config(false, contextUser);
+            const template = TemplateEngineServer.Instance.Templates?.find(t => UUIDsEqual(t.ID, prompt.TemplateID));
+            return template?.GetHighestPriorityContent()?.TemplateText ?? null;
+        }
+        catch (e) {
+            this.logError(e instanceof Error ? e : String(e), { category: 'RuntimeStateFragment', severity: 'warning' });
+            return null;
+        }
+    }
+    /**
+     * The child prompt's raw template text (placeholders intact), from the cached template engine.
+     * Null when the prompt has no template or the lookup fails — which fails CLOSED: with no text to
+     * inspect, {@link ResolveSpecializationPlacement} keeps the specialization in the system prompt.
+     */
+    async loadChildPromptTemplateText(childPrompt, contextUser) {
+        return this.loadPromptTemplateText(childPrompt, contextUser);
+    }
+    /**
+     * The date/time strings exactly as the system placeholders would render them into the template.
+     * Resolves only the three temporal placeholders (by name, through the same registry the template
+     * uses, so a registered override applies here too) rather than every system placeholder — this runs
+     * on every loop iteration.
+     */
+    async resolveFragmentDateTime(promptParams) {
+        const resolve = async (name) => {
+            const placeholder = SystemPlaceholderManager.getPlaceholders().find(p => p.name === name);
+            if (!placeholder) {
+                return null;
+            }
+            try {
+                const value = await placeholder.getValue(promptParams);
+                return value == null ? null : String(value);
+            }
+            catch (e) {
+                this.logError(e instanceof Error ? e : String(e), { category: 'RuntimeStateFragment', severity: 'warning', metadata: { placeholder: name } });
+                return null;
+            }
+        };
+        const [date, dayOfWeek, time] = await Promise.all([resolve(CURRENT_DATE_PLACEHOLDER), resolve(CURRENT_DAY_OF_WEEK_PLACEHOLDER), resolve(CURRENT_TIME_PLACEHOLDER)]);
+        if (!date || !dayOfWeek || !time) {
+            return null;
+        }
+        return { Date: date, DayOfWeek: dayOfWeek, Time: time };
+    }
+    /**
+     * The scratchpad strings already placed in the template data by the prep step (so the fragment shows
+     * exactly what the template would have). Null when the scratchpad is disabled or absent.
+     */
+    readScratchpadFromTemplateData(data) {
+        const notes = data[SCRATCHPAD_NOTES_PLACEHOLDER], tasks = data[SCRATCHPAD_TASKS_PLACEHOLDER], summary = data[SCRATCHPAD_TASK_SUMMARY_PLACEHOLDER];
+        if (typeof notes !== 'string' || typeof tasks !== 'string' || typeof summary !== 'string') {
+            return null;
+        }
+        return { Notes: notes, Tasks: tasks, TaskSummary: summary };
+    }
     /**
      * Executes the configured prompt. Always uses the attemptJSONRepair option to try to fix LLM
      * JSON syntax issues if they arise.
@@ -4211,7 +4832,7 @@ export class BaseAgent {
         }
         // Check absolute maximum iterations (safety net to prevent infinite loops)
         const absoluteMaxIterations = params.absoluteMaxIterations ?? BaseAgent.DEFAULT_ABSOLUTE_MAX_ITERATIONS;
-        if (agentRun.TotalPromptIterations && agentRun.TotalPromptIterations >= absoluteMaxIterations) {
+        if (agentRun.TotalPromptIterations != null && agentRun.TotalPromptIterations >= absoluteMaxIterations) {
             return {
                 exceeded: true,
                 type: 'iterations',
@@ -4221,7 +4842,7 @@ export class BaseAgent {
             };
         }
         // Check cost limit
-        if (agent.MaxCostPerRun && agentRun.TotalCost) {
+        if (agent.MaxCostPerRun != null && agentRun.TotalCost != null) {
             if (agentRun.TotalCost >= agent.MaxCostPerRun) {
                 return {
                     exceeded: true,
@@ -4233,7 +4854,7 @@ export class BaseAgent {
             }
         }
         // Check token limit
-        if (agent.MaxTokensPerRun && agentRun.TotalTokensUsed) {
+        if (agent.MaxTokensPerRun != null && agentRun.TotalTokensUsed != null) {
             if (agentRun.TotalTokensUsed >= agent.MaxTokensPerRun) {
                 return {
                     exceeded: true,
@@ -4245,7 +4866,7 @@ export class BaseAgent {
             }
         }
         // Check iteration limit
-        if (agent.MaxIterationsPerRun && agentRun.TotalPromptIterations) {
+        if (agent.MaxIterationsPerRun != null && agentRun.TotalPromptIterations != null) {
             if (agentRun.TotalPromptIterations >= agent.MaxIterationsPerRun) {
                 return {
                     exceeded: true,
@@ -4257,7 +4878,7 @@ export class BaseAgent {
             }
         }
         // Check time limit
-        if (agent.MaxTimePerRun && agentRun.StartedAt) {
+        if (agent.MaxTimePerRun != null && agentRun.StartedAt) {
             const elapsedSeconds = Math.floor((Date.now() - new Date(agentRun.StartedAt).getTime()) / 1000);
             if (elapsedSeconds >= agent.MaxTimePerRun) {
                 return {
@@ -4625,6 +5246,60 @@ export class BaseAgent {
     serializePayloadAtEnd(payload) {
         return payload ? JSON.stringify(payload) : null;
     }
+    /**
+     * Recovery Strategy 0: drop stale runtime-state fragments.
+     *
+     * Under append-only trailing-state retention (prefix-cache providers: OpenAI, xAI) every
+     * iteration leaves its `<mj-runtime-state>` message in the history so the next request is an
+     * exact prefix extension of the last. Those copies are cached tokens on the wire, but they are
+     * context all the same, and they carry nothing the model needs: the CURRENT state always rides
+     * as the fresh fragment appended to the outgoing request. So when the context overflows they
+     * are the first thing to go, oldest first, all but the most recent. Keeping the newest one
+     * matters for two reasons: it is the history's only fragment after this pass, so
+     * {@link restoreTurn1VolatileStateIfNeeded} does not splice a turn-1 copy back in, and it
+     * keeps the prefix intact from that point forward. The cost is one cache miss on the next call;
+     * the alternative was a failed run.
+     *
+     * A no-op under replace-in-place retention, where the history never holds a fragment.
+     *
+     * @param params - Agent execution parameters
+     * @param tokensToSave - Target number of tokens to free
+     * @param currentStepCount - Current turn number, for the lifecycle event
+     * @returns Result with tokens saved and strategy description
+     * @protected
+     */
+    recoveryStrategy_DropStaleVolatileState(params, tokensToSave, currentStepCount) {
+        const fragmentIndices = params.conversationMessages
+            .map((msg, index) => (msg.metadata?.volatileState === true ? index : -1))
+            .filter(index => index >= 0);
+        // All but the most recent, oldest first.
+        const stale = fragmentIndices.slice(0, -1);
+        if (stale.length === 0) {
+            return { tokensSaved: 0, strategyName: 'No stale runtime-state fragments to drop' };
+        }
+        let tokensSaved = 0;
+        const removedIndices = [];
+        for (const index of stale) {
+            if (tokensSaved >= tokensToSave)
+                break;
+            removedIndices.push(index);
+            tokensSaved += this.estimateTokens(params.conversationMessages[index].content);
+        }
+        // Remove in reverse order to keep the remaining indices valid.
+        removedIndices.sort((a, b) => b - a).forEach(index => {
+            const removed = params.conversationMessages.splice(index, 1)[0];
+            this.emitMessageLifecycleEvent({
+                type: 'message-removed',
+                turn: currentStepCount,
+                messageIndex: index,
+                message: removed,
+                reason: 'Context recovery - stale runtime-state fragment (append-only retention)',
+                tokensSaved: this.estimateTokens(removed.content)
+            });
+        });
+        this.logStatus(`Dropped ${removedIndices.length} stale runtime-state fragment(s) (${tokensSaved} tokens); ${fragmentIndices.length - removedIndices.length} retained`, true, params);
+        return { tokensSaved, strategyName: `Dropped ${removedIndices.length} stale runtime-state fragment(s) retained for prefix caching` };
+    }
     /**
      * Recovery Strategy 1: Remove oldest tool-result messages.
      * Targets messages older than minAge turns for removal.
@@ -4730,7 +5405,7 @@ export class BaseAgent {
                 : JSON.stringify(originalMessage.content);
             if (originalMessage.role === 'tool') {
                 // compact each tool_result block's text; the block structure is what the provider needs.
-                const compacted = compactToolResultContent(originalMessage, (t) => (t.length > 500 ? `${t.slice(0, 500)}… [compacted from ${t.length} chars]` : t));
+                const compacted = CompactToolResultContent(originalMessage, (t) => (t.length > 500 ? `${t.slice(0, 500)}… [compacted from ${t.length} chars]` : t));
                 const saved = originalTokens - this.estimateTokens(compacted.content);
                 if (saved > 0) {
                     params.conversationMessages[candidate.index] = {
@@ -4845,10 +5520,13 @@ export class BaseAgent {
      * @protected
      */
     recoveryStrategy_TrimLastUserMessage(params, tokensToSave) {
-        // Find the last user message (reverse search for compatibility)
+        // Find the last user message (reverse search for compatibility). A retained runtime-state
+        // fragment is user-role but is framework state, not the user's request: trimming it would
+        // leave a damaged copy in the history and spare the message this strategy is meant to trim.
         let lastUserMessageIndex = -1;
         for (let i = params.conversationMessages.length - 1; i >= 0; i--) {
-            if (params.conversationMessages[i].role === 'user') {
+            const candidate = params.conversationMessages[i];
+            if (candidate.role === 'user' && candidate.metadata?.volatileState !== true) {
                 lastUserMessageIndex = i;
                 break;
             }
@@ -4922,6 +5600,9 @@ export class BaseAgent {
         const currentPromptTurn = this._promptTurnCount;
         // Try multiple recovery strategies in order
         const strategies = [
+            // Retained runtime-state fragments (append-only mode) are pure cache filler: stale copies of
+            // state the next request re-sends anyway. Freeing them costs one cache miss, never content.
+            () => this.recoveryStrategy_DropStaleVolatileState(params, tokensToSave, currentPromptTurn),
             () => this.recoveryStrategy_RemoveOldestToolResults(params, tokensToSave, currentPromptTurn, 5),
             () => this.recoveryStrategy_CompactOldToolResults(params, tokensToSave, currentPromptTurn, 3),
             () => this.recoveryStrategy_RemoveOldestToolResults(params, tokensToSave, currentPromptTurn, 2),
@@ -4988,7 +5669,7 @@ The context is now within limits. Please retry your request with the recovered c
         // if we need to retry make sure we add the retry message to the conversation messages
         if (guardrailCheckedStep.step === 'Retry' && guardrailCheckedStep.payloadToolCallId && guardrailCheckedStep.nativeTurn?.sendResultsNatively) {
             // the payload-only turn is answered as a tool result for the payload_change_request call.
-            params.conversationMessages.push(buildToolResultTurn([{
+            params.conversationMessages.push(BuildToolResultTurn([{
                     toolCallId: guardrailCheckedStep.payloadToolCallId,
                     toolName: 'payload_change_request',
                     content: guardrailCheckedStep.retryInstructions || 'Payload change applied.',
@@ -5059,10 +5740,12 @@ The context is now within limits. Please retry your request with the recovered c
      * its direct predecessor's results, so context never compounds.
      *
      * Gated on conversationId + root depth — programmatic runs and sub-agents skip it.
+     * Skipped under a history floor (`ConversationHistoryFrom`): the previous run's tool
+     * results can quote messages from before the floor.
      * @protected
      */
     async injectPriorTurnToolResults(params) {
-        if (!params.conversationId || this._depth !== 0) {
+        if (!params.conversationId || this._depth !== 0 || params.ConversationHistoryFrom) {
             return;
         }
         try {
@@ -5301,6 +5984,11 @@ The context is now within limits. Please retry your request with the recovered c
                 promptParams.data = { lens, messages: rangeText };
                 promptParams.contextUser = params.contextUser;
                 promptParams.agentId = params.agent.ID;
+                promptParams.UserID = ResolvePromptRunUserID({
+                    UserID: params.userId,
+                    AgentRun: this._agentRun,
+                    ContextUser: params.contextUser,
+                }) ?? undefined;
                 const result = await this._promptRunner.ExecutePrompt(promptParams);
                 const text = ExtractPromptResultText(result);
                 if (!result.success || text.length === 0) {
@@ -5625,8 +6313,11 @@ The context is now within limits. Please retry your request with the recovered c
         };
         // Operators (where/select/map/…) are pure code-defined verbs, not registry tools — only
         // capabilities (Actions + artifact tools) live here as pipeline sources/stages.
-        // Actions — each wrapped to run via the existing single-action execution path.
-        this.getEffectiveActionsForValidation(params.agent.ID).forEach((actionEntity) => register(new ActionInvocable(actionEntity.Name, (p) => this.ExecuteSingleAction(params, { name: actionEntity.Name, params: p }, actionEntity, params.contextUser))));
+        // Actions — each wrapped to run via the existing single-action execution path. The
+        // run-scoped circuit breaker is bypassed here: the pipeline executor's `map` stage does
+        // its own per-element failure accounting and expects elements to be independent, and
+        // there is no model in that loop to act on the breaker's guidance.
+        this.getEffectiveActionsForValidation(params.agent.ID).forEach((actionEntity) => register(new ActionInvocable(actionEntity.Name, (p) => this.ExecuteSingleAction(params, { name: actionEntity.Name, params: p }, actionEntity, params.contextUser, { skipCircuitBreaker: true }))));
         // Artifact tools — one invocable per distinct tool name; `artifactId` is supplied as a
         // call-time param so the same `{ tool, params }` step shape works across all substrates.
         this._artifactToolManager.GetAvailableToolNames().forEach((toolName) => register(new ArtifactToolInvocable(toolName, async (tool, p) => {
@@ -6120,6 +6811,33 @@ The context is now within limits. Please retry your request with the recovered c
             return {};
         }
     }
+    /**
+     * Whether THIS action may use the run's runtime API key for THIS driver class. The default is
+     * yes: the run was started on those keys, and an action that calls a vendor on the user's behalf
+     * (Generate Image) is doing what the prompts do. Override to narrow it — an agent that knows
+     * which of its actions talk to which vendor can refuse everything else, and a refusal costs the
+     * action nothing but the customer's key: it falls back to the platform key as if the run had none.
+     */
+    actionMayUseRuntimeAPIKey(action, driverClass, params) {
+        return true;
+    }
+    /**
+     * The {@link RuntimeAPIKeyResolver} handed to one action dispatch: one driver class in, one key
+     * out, the list itself never leaves this closure. Every answer is logged by action and driver
+     * class (never the key), so a run's log shows which action drew which credential.
+     */
+    buildRuntimeAPIKeyResolver(params, actionEntity) {
+        const runKeys = params.apiKeys;
+        return (driverClass) => {
+            if (!this.actionMayUseRuntimeAPIKey(actionEntity, driverClass, params)) {
+                this.logStatus(`🔑 Runtime API key for '${driverClass}' refused to action '${actionEntity.Name}' by policy — platform key applies`, true, params);
+                return undefined;
+            }
+            const key = GetAIAPIKey(driverClass, runKeys);
+            this.logStatus(`🔑 Action '${actionEntity.Name}' resolved an API key for '${driverClass}' (${runKeys?.some((k) => k.driverClass === driverClass) ? 'run' : 'platform'})`, true, params);
+            return key || undefined;
+        };
+    }
     /**
      * This method executes one action using the MemberJunction Actions framework.
      * The full ActionResult objects are returned, allowing the caller to access result codes, output parameters,
@@ -6128,12 +6846,24 @@ The context is now within limits. Please retry your request with the recovered c
      * @param {ExecuteAgentParams} params - Parameters from agent execution for context passing
      * @param {AgentAction} action - Action to execute
      * @param {UserInfo} [contextUser] - Optional user context for permissions
+     * @param {ExecuteSingleActionOptions} [options] - `skipCircuitBreaker` bypasses the run-scoped
+     *   circuit breaker for callers that do their own failure accounting (the pipeline executor)
      *
      * @returns {Promise<ActionResult>} ActionResult object from the action execution
      *
      * @throws {Error} If the action fails to execute
      */
-    async ExecuteSingleAction(params, action, actionEntity, contextUser) {
+    async ExecuteSingleAction(params, action, actionEntity, contextUser, options) {
+        const skipBreaker = options?.skipCircuitBreaker === true;
+        const normalizedParams = this.normalizeActionParams(action.params);
+        // Run-scoped circuit breaker: each rule short-circuits in 0ms with a result that carries the
+        // rule that fired, so the failure directive can name it without consulting the history.
+        if (!skipBreaker) {
+            const blocked = this.checkActionCircuitBreaker(params, action, actionEntity, normalizedParams);
+            if (blocked) {
+                return blocked;
+            }
+        }
         try {
             const actionEngine = ActionEngineServer.Instance;
             // Convert params object to ActionParam array
@@ -6165,17 +6895,34 @@ The context is now within limits. Please retry your request with the recovered c
                 ContextUser: contextUser,
                 Filters: [],
                 SkipActionLog: false,
-                Context: actionContext
+                Context: actionContext,
+                // The run's RUNTIME API KEYS, as a RESOLVER bound to this one action — see
+                // buildRuntimeAPIKeyResolver(). Per dispatch on purpose: actionContext IS params.context,
+                // shared by every action in the run (parallel ones included) and copied into sub-agent
+                // runs, so anything stamped there would name the wrong action under parallel dispatch
+                // and travel further than the action it was meant for. Absent when the run has no keys,
+                // so the action uses GetAIAPIKey(driverClass) exactly as before.
+                RuntimeAPIKeyResolver: params.apiKeys && params.apiKeys.length > 0 ? this.buildRuntimeAPIKeyResolver(params, actionEntity) : undefined,
             });
             if (result.Success) {
                 this.logStatus(`   ✅ Action '${action.name}' completed successfully`, true, params);
+                if (!skipBreaker) {
+                    this.clearActionFailureRecord(action, actionEntity);
+                }
             }
             else {
                 this.logStatus(`   ❌ Action '${action.name}' failed: ${result.Message || 'Unknown error'}`, false, params);
+                if (!skipBreaker) {
+                    this.recordActionFailure(action, actionEntity, result.Message, normalizedParams);
+                }
             }
             return result;
         }
         catch (error) {
+            const errorMsg = error instanceof Error ? error.message : String(error);
+            if (!skipBreaker) {
+                this.recordActionFailure(action, actionEntity, errorMsg, normalizedParams);
+            }
             this.logError(error, {
                 category: 'ActionExecution',
                 metadata: {
@@ -6256,6 +7003,13 @@ The context is now within limits. Please retry your request with the recovered c
      * **Priority:** AIAgentRelationship.MessageMode takes precedence over AIAgent.MessageMode
      * to allow different parent agents to pass messages differently to the same sub-agent.
      *
+     * **Runtime state never crosses the boundary.** The parent's trailing runtime-state messages
+     * (`metadata.volatileState` — its payload, scratchpad and, when relocated, its specialization;
+     * retained in the history under append-only mode) are dropped BEFORE any mode slices the
+     * history, so a sub-agent never sees the parent's state, never has it counted against
+     * `MaxMessages`, and never receives it unescaped when it builds no fragment of its own. The
+     * sub-agent builds its own fragment at its prompt step.
+     *
      * Subclasses can override this method to implement custom message preparation logic
      * specific to their domain (e.g., Skip agents adding special context).
      *
@@ -6275,6 +7029,9 @@ The context is now within limits. Please retry your request with the recovered c
         // Get MessageMode and MaxMessages from either relationship or child agent
         let messageMode = relationship?.MessageMode || subAgent.MessageMode || 'None';
         let maxMessages = relationship?.MaxMessages || subAgent.MaxMessages || null;
+        // The parent's history minus its runtime-state messages (see the doc comment): every mode
+        // slices THIS, so no fragment reaches the sub-agent and none spends a MaxMessages slot.
+        const history = params.conversationMessages.filter(m => m.metadata?.volatileState !== true);
         // Apply message mode
         switch (messageMode) {
             case 'None':
@@ -6283,23 +7040,23 @@ The context is now within limits. Please retry your request with the recovered c
                 break;
             case 'All':
                 // Pass all parent conversation history
-                messages = [...params.conversationMessages];
+                messages = [...history];
                 break;
             case 'Latest':
                 // Pass most recent N messages
                 if (maxMessages && maxMessages > 0) {
-                    messages = this.makeToolTurnsSelfConsistent(params.conversationMessages.slice(-maxMessages));
+                    messages = this.makeToolTurnsSelfConsistent(history.slice(-maxMessages));
                 }
                 else {
-                    messages = [...params.conversationMessages];
+                    messages = [...history];
                 }
                 break;
             case 'Bookend':
                 // Pass first 2 + most recent (N-2) with indicator message between
-                if (maxMessages && maxMessages > 2 && params.conversationMessages.length > maxMessages) {
-                    const firstTwo = params.conversationMessages.slice(0, 2);
-                    const remaining = params.conversationMessages.slice(-(maxMessages - 2));
-                    const omittedCount = params.conversationMessages.length - maxMessages;
+                if (maxMessages && maxMessages > 2 && history.length > maxMessages) {
+                    const firstTwo = history.slice(0, 2);
+                    const remaining = history.slice(-(maxMessages - 2));
+                    const omittedCount = history.length - maxMessages;
                     messages = this.makeToolTurnsSelfConsistent([
                         ...firstTwo,
                         {
@@ -6310,7 +7067,7 @@ The context is now within limits. Please retry your request with the recovered c
                     ]);
                 }
                 else {
-                    messages = [...params.conversationMessages];
+                    messages = [...history];
                 }
                 break;
             default:
@@ -6407,6 +7164,7 @@ The context is now within limits. Please retry your request with the recovered c
                 subAgentChanges: subAgentSubAgentChanges, // propagate filtered sub-agent changes to sub-agent
                 PrimaryScopeEntityName: params.PrimaryScopeEntityName, // propagate scope to sub-agent
                 PrimaryScopeRecordID: params.PrimaryScopeRecordID,
+                companyId: params.companyId,
                 SecondaryScopes: params.SecondaryScopes,
                 onAgentRunCreated: async (agentRunId) => {
                     stepEntity.TargetLogID = agentRunId;
@@ -7759,7 +8517,7 @@ The context is now within limits. Please retry your request with the recovered c
                 await this.recordFoldedTaskGraph(params, previousDecision);
                 return await this.processSubAgentStep(params, previousDecision, undefined, undefined, stepCount);
             case 'Actions':
-                return await this.executeActionsStep(params, previousDecision, undefined, true, stepCount);
+                return await this.executeActionsStep(params, previousDecision, undefined, true, stepCount, this.actionOptionsForAgentType());
             // Type assertion required because 'Skill' is not part of the BaseAgentNextStep step
             // union (non-terminal, like 'ClientTools') — LoopAgentType.DetermineNextStep() emits it
             // when the LLM chooses to activate a skill.
@@ -8650,9 +9408,9 @@ The context is now within limits. Please retry your request with the recovered c
             }
             if (previousDecision?.nativeTurn?.sendResultsNatively && subAgentRequest.toolCallId) {
                 // the delegate_to_* call is answered as a tool result.
-                params.conversationMessages.push(buildToolResultTurn([...this.payloadToolResult(previousDecision), {
+                params.conversationMessages.push(BuildToolResultTurn([...this.payloadToolResult(previousDecision), {
                         toolCallId: subAgentRequest.toolCallId,
-                        toolName: `${SUB_AGENT_TOOL_PREFIX}${sanitizeToolName(subAgentRequest.name)}`,
+                        toolName: `${SUB_AGENT_TOOL_PREFIX}${SanitizeToolName(subAgentRequest.name)}`,
                         content: resultMessage,
                         isError: !subAgentResult.success
                     }], subAgentMetadata));
@@ -9144,11 +9902,11 @@ The context is now within limits. Please retry your request with the recovered c
         const pairable = nativeResults ? allExecutions.filter((e) => !!e.request.toolCallId) : [];
         const unpairable = allExecutions.filter((e) => !pairable.includes(e));
         if (pairable.length > 0) {
-            params.conversationMessages.push(buildToolResultTurn([
+            params.conversationMessages.push(BuildToolResultTurn([
                 ...this.payloadToolResult(previousDecision),
                 ...pairable.map((e) => ({
                     toolCallId: e.request.toolCallId,
-                    toolName: `${SUB_AGENT_TOOL_PREFIX}${sanitizeToolName(e.request.name)}`,
+                    toolName: `${SUB_AGENT_TOOL_PREFIX}${SanitizeToolName(e.request.name)}`,
                     content: this.buildParallelSubAgentSummary([e]),
                     isError: !e.result.success
                 }))
@@ -9372,9 +10130,9 @@ The context is now within limits. Please retry your request with the recovered c
             }
             if (previousDecision.nativeTurn?.sendResultsNatively && subAgentRequest.toolCallId) {
                 // the delegate_to_* call is answered as a tool result (same as the child path).
-                params.conversationMessages.push(buildToolResultTurn([...this.payloadToolResult(previousDecision), {
+                params.conversationMessages.push(BuildToolResultTurn([...this.payloadToolResult(previousDecision), {
                         toolCallId: subAgentRequest.toolCallId,
-                        toolName: `${SUB_AGENT_TOOL_PREFIX}${sanitizeToolName(subAgentRequest.name)}`,
+                        toolName: `${SUB_AGENT_TOOL_PREFIX}${SanitizeToolName(subAgentRequest.name)}`,
                         content: relatedResultMessage,
                         isError: !subAgentResult.success
                     }], relatedMetadata));
@@ -9623,12 +10381,21 @@ The context is now within limits. Please retry your request with the recovered c
      * Supports both dot notation (obj.prop) and array indexing (arr[0]).
      *
 
+    /**
+     * The {@link ExecuteSingleActionOptions} the main loop passes for this run's agent type: the
+     * circuit-breaker exemption when the type has opted out (`BaseAgentType.UsesActionCircuitBreaker`
+     * is false — Flow), otherwise none. Kept as a seam so a subclass can widen or narrow the
+     * exemption without touching the loop.
+     */
+    actionOptionsForAgentType() {
+        return this.AgentTypeInstance?.UsesActionCircuitBreaker === false ? { skipCircuitBreaker: true } : undefined;
+    }
     /**
      * Executes actions step and tracks it.
      *
      * @private
      */
-    async executeActionsStep(params, previousDecision, parentStepId, addConversationMessage = true, stepCount = 0) {
+    async executeActionsStep(params, previousDecision, parentStepId, addConversationMessage = true, stepCount = 0, actionOptions) {
         try {
             const currentPayload = previousDecision?.newPayload || previousDecision?.previousPayload || params.payload;
             const actions = previousDecision.actions || [];
@@ -9788,7 +10555,7 @@ The context is now within limits. Please retry your request with the recovered c
                 let actionResult;
                 try {
                     // Execute the action
-                    actionResult = await this.ExecuteSingleAction(params, aa, actionEntity, params.contextUser);
+                    actionResult = await this.ExecuteSingleAction(params, aa, actionEntity, params.contextUser, actionOptions);
                     // Update step entity with ActionExecutionLog ID if available
                     if (actionResult.LogEntry?.ID) {
                         const logId = actionResult.LogEntry.ID;
@@ -9808,7 +10575,7 @@ The context is now within limits. Please retry your request with the recovered c
                     };
                     // Finalize step entity with output data
                     await this.finalizeStepEntity(stepEntity, actionResult.Success, actionResult.Success ? undefined : actionResult.Message, outputData);
-                    return { success: true, result: actionResult, action: aa, actionEntity, stepEntity };
+                    return { success: actionResult.Success, result: actionResult, action: aa, actionEntity, stepEntity, error: actionResult.Success ? undefined : actionResult.Message };
                 }
                 catch (error) {
                     await this.finalizeStepEntity(stepEntity, false, error.message);
@@ -9824,9 +10591,10 @@ The context is now within limits. Please retry your request with the recovered c
             // Build a clean summary of action results
             // Apply large binary content interception to prevent context overflow
             const actionSummaries = actionResults.map(result => {
-                const actionResult = result.success ? result.result : null;
+                const actionResult = result.result;
+                const isActionSuccess = Boolean(result.success && (actionResult ? actionResult.Success : true));
                 // Filter to output params only
-                const outputParams = result.result?.Params?.filter(p => p.Type === 'Both' || p.Type === 'Output') || [];
+                const outputParams = actionResult?.Params?.filter(p => p.Type === 'Both' || p.Type === 'Output') || [];
                 // Intercept large media content (images, audio, video) and replace with placeholders
                 // This prevents context overflow from base64 data (~700K tokens per 1024x1024 image)
                 // Pass actionEntity for generic ValueType=MediaOutput detection from metadata
@@ -9836,11 +10604,12 @@ The context is now within limits. Please retry your request with the recovered c
                 this._fileOutputs.push(...fileOutputs);
                 return {
                     actionName: result.action.name,
-                    success: result.success,
+                    success: isActionSuccess,
                     params: sanitizedParams,
-                    resultCode: actionResult?.Result?.ResultCode || (result.success ? 'SUCCESS' : 'ERROR'),
-                    message: result.success ? actionResult?.Message || 'Action completed' : result.error || 'Unknown error',
-                    aiDirectives: result.success ? actionResult?.AIDirectives : undefined
+                    resultCode: actionResult?.Result?.ResultCode || (isActionSuccess ? 'SUCCESS' : 'ERROR'),
+                    message: actionResult?.Message || (isActionSuccess ? 'Action completed' : result.error || 'Unknown error'),
+                    aiDirectives: isActionSuccess ? actionResult?.AIDirectives : undefined,
+                    breakerReason: actionResult instanceof CircuitBreakerActionResult ? actionResult.Reason : undefined
                 };
             });
             // Check if any actions failed
@@ -9906,6 +10675,16 @@ The context is now within limits. Please retry your request with the recovered c
                         content: `IMPORTANT — Follow these directives from the action results:\n\n${directiveText}`
                     });
                 }
+                // Surface failure guidance for failed actions so the model does not repeatedly loop on broken
+                // tools. Not when the breaker is bypassed for this step: there is then no model in the loop to
+                // act on it (Flow, ForEach, While, pipeline), and the directive would only pollute the history.
+                if (failedActions.length > 0 && actionOptions?.skipCircuitBreaker !== true) {
+                    const failureText = failedActions.map(f => this.formatActionFailureDirective(f)).join('\n\n');
+                    params.conversationMessages.push({
+                        role: 'user',
+                        content: `IMPORTANT — Action Execution Failure Guidance:\n\n${failureText}`
+                    });
+                }
             }
             // Call agent type's post-processing for actions
             let finalPayload = currentPayload;
@@ -11174,16 +11953,18 @@ The context is now within limits. Please retry your request with the recovered c
     async executeForEachLoop(params, config, previousDecision) {
         const forEach = previousDecision.forEach;
         if (!forEach) {
+            // Not reported to the model: a Loop agent never gets here, because LoopAgentType turns a
+            // ForEach step with no details into a Retry whose errorMessage the model is shown.
             return this.createFailedStep('ForEach configuration missing', previousDecision);
         }
         const validationMessage = this.validateForEachOperation(forEach);
         if (validationMessage) {
-            return this.createFailedStep(`ForEach configuration invalid: ${validationMessage}`, previousDecision);
+            return this.failLoopBeforeFirstIteration('ForEach', forEach.collectionPath, `ForEach configuration invalid: ${validationMessage}`, previousDecision, params, forEach.action?.name);
         }
         const currentPayload = previousDecision.newPayload || previousDecision.previousPayload;
         const collection = this.getCollectionFromPayload(currentPayload, forEach.collectionPath);
         if (!collection) {
-            return this.createFailedStep(`Collection path "${forEach.collectionPath}" not an array`, previousDecision);
+            return this.failLoopBeforeFirstIteration('ForEach', forEach.collectionPath, `Collection path "${forEach.collectionPath}" not an array`, previousDecision, params, forEach.action?.name);
         }
         const loopStepEntity = await this.createForEachLoopStep(forEach, collection, currentPayload, params);
         const loopResults = await this.executeForEachIterations(forEach, collection, currentPayload, loopStepEntity.ID, params, config);
@@ -11461,7 +12242,9 @@ The context is now within limits. Please retry your request with the recovered c
                     params: resolvedParams
                 };
                 const actionStep = { step: 'Actions', actions: [resolvedAction], newPayload: currentPayload, previousPayload: currentPayload, terminate: false };
-                result = await this.executeActionsStep(params, actionStep, parentStepId, false);
+                // Loop iterations bypass the circuit breaker: the loop does its own per-item accounting and
+                // there is no model between items to act on the breaker's guidance.
+                result = await this.executeActionsStep(params, actionStep, parentStepId, false, 0, { skipCircuitBreaker: true });
             }
             else if (forEach.subAgent) {
                 const subAgentStep = { step: 'Sub-Agent', subAgent: forEach.subAgent, newPayload: currentPayload, previousPayload: currentPayload };
@@ -11487,7 +12270,7 @@ The context is now within limits. Please retry your request with the recovered c
     async completeForEachLoop(forEach, loopStepEntity, loopResults, previousDecision, params) {
         // Finalize the loop step now that loop is complete
         loopStepEntity.PayloadAtEnd = this.serializePayloadAtEnd(loopResults.finalPayload);
-        await this.finalizeStepEntity(loopStepEntity, loopResults.errors.length === 0, loopResults.errors.join('\n\n'), loopResults);
+        await this.finalizeStepEntity(loopStepEntity, loopResults.errors.length === 0, this.formatLoopErrors(loopResults.errors), loopResults);
         if (this.AgentTypeInstance.InjectLoopResultsAsMessage) {
             this.injectLoopResultsMessage('ForEach', forEach.collectionPath, loopResults.results, loopResults.errors, params, forEach.action?.name);
         }
@@ -11517,6 +12300,32 @@ The context is now within limits. Please retry your request with the recovered c
             metadata
         });
     }
+    /**
+     * Fails a loop that never ran an iteration, and tells the model why.
+     *
+     * A Loop agent answers a Failed step by prompting again (`HandleStepFallback` returns null), and
+     * nothing on that path reads the step's `errorMessage`. Without the injected message the model
+     * gets another turn with no idea its loop failed, and is likely to emit the same loop again.
+     * Flow agents don't inject loop results, so for them this is just the Failed step.
+     */
+    failLoopBeforeFirstIteration(loopType, collectionOrCondition, errorMessage, previousDecision, params, actionName) {
+        if (this.AgentTypeInstance.InjectLoopResultsAsMessage) {
+            this.injectLoopResultsMessage(loopType, collectionOrCondition, [], [{ index: 0, message: errorMessage }], params, actionName);
+        }
+        return this.createFailedStep(errorMessage, previousDecision);
+    }
+    /**
+     * One loop error as readable text. Joining the error objects directly wrote "[object Object]"
+     * into the step's ErrorMessage. Falls back to JSON when an iteration threw something with no
+     * message (a thrown non-Error).
+     */
+    describeLoopError(err) {
+        return err.message ? err.message : JSON.stringify(err);
+    }
+    /** All loop errors as text for a step's ErrorMessage. */
+    formatLoopErrors(errors) {
+        return errors.map(err => this.describeLoopError(err)).join('\n\n');
+    }
     /**
      * Formats loop iteration results as markdown. Handles two distinct result shapes
      * depending on whether the loop body executed actions or sub-agents:
@@ -11557,8 +12366,7 @@ The context is now within limits. Please retry your request with the recovered c
         if (errors.length > 0) {
             lines.push(`### Errors`);
             for (const err of errors) {
-                const errMsg = typeof err === 'string' ? err : err?.message || JSON.stringify(err);
-                lines.push(`• ✗ ${errMsg}`);
+                lines.push(`• ✗ ${this.describeLoopError(err)}`);
             }
         }
         return lines.join('\n');
@@ -11664,11 +12472,13 @@ The context is now within limits. Please retry your request with the recovered c
     async executeWhileLoop(params, config, previousDecision) {
         const whileOp = previousDecision.while;
         if (!whileOp) {
+            // Not reported to the model: a Loop agent never gets here, because LoopAgentType turns a
+            // While step with no details into a Retry whose errorMessage the model is shown.
             return this.createFailedStep('While configuration missing', previousDecision);
         }
         const validationMessage = this.validateWhileOperation(whileOp);
         if (validationMessage) {
-            return this.createFailedStep(`While configuration invalid: ${validationMessage}`, previousDecision);
+            return this.failLoopBeforeFirstIteration('While', whileOp.condition, `While configuration invalid: ${validationMessage}`, previousDecision, params, whileOp.action?.name);
         }
         const currentPayload = previousDecision.newPayload || previousDecision.previousPayload;
         const loopStepEntity = await this.createWhileLoopStep(whileOp, currentPayload, params);
@@ -11697,6 +12507,7 @@ The context is now within limits. Please retry your request with the recovered c
         const results = [];
         const errors = [];
         let iterationCount = 0;
+        let conditionError;
         const evaluator = new SafeExpressionEvaluator();
         // ACTUAL WHILE LOOP - simple and clear!
         while (iterationCount < maxIterations) {
@@ -11704,7 +12515,15 @@ The context is now within limits. Please retry your request with the recovered c
                 await new Promise(resolve => setTimeout(resolve, whileOp.delayBetweenIterationsMs));
             }
             const evalResult = evaluator.evaluate(whileOp.condition, { payload: currentPayload, results, errors });
-            if (!evalResult.success || !evalResult.value) {
+            if (!evalResult.success) {
+                // "Could not evaluate" is not "evaluated false". Treating it as false used to end the
+                // loop silently and finalize it as a success — a malformed condition produced a green,
+                // zero-iteration loop with the evaluator's error discarded.
+                conditionError = `While condition '${whileOp.condition}' could not be evaluated: ${evalResult.error ?? 'unknown error'}`;
+                errors.push({ index: iterationCount, message: conditionError });
+                break;
+            }
+            if (!evalResult.value) {
                 break;
             }
             const attemptContext = { attemptNumber: iterationCount + 1, totalAttempts: iterationCount };
@@ -11720,7 +12539,7 @@ The context is now within limits. Please retry your request with the recovered c
             }
             iterationCount++;
         }
-        return { results, errors, finalPayload: currentPayload, iterations: iterationCount };
+        return { results, errors, finalPayload: currentPayload, iterations: iterationCount, conditionError };
     }
     /**
      * Helper: Execute single While iteration
@@ -11749,7 +12568,8 @@ The context is now within limits. Please retry your request with the recovered c
                     params: resolvedParams
                 };
                 const actionStep = { step: 'Actions', actions: [resolvedAction], newPayload: currentPayload, previousPayload: currentPayload, terminate: false };
-                result = await this.executeActionsStep(params, actionStep, parentStepId, false);
+                // Same exemption as ForEach: the loop owns per-iteration accounting.
+                result = await this.executeActionsStep(params, actionStep, parentStepId, false, 0, { skipCircuitBreaker: true });
             }
             else if (whileOp.subAgent) {
                 const subAgentStep = { step: 'Sub-Agent', subAgent: whileOp.subAgent, newPayload: currentPayload, previousPayload: currentPayload };
@@ -11774,13 +12594,23 @@ The context is now within limits. Please retry your request with the recovered c
      */
     async completeWhileLoop(whileOp, loopStepEntity, loopResults, previousDecision, params) {
         loopStepEntity.PayloadAtEnd = this.serializePayloadAtEnd(loopResults.finalPayload);
-        await this.finalizeStepEntity(loopStepEntity, loopResults.errors.length === 0, loopResults.errors.join('\n\n'), loopResults);
+        await this.finalizeStepEntity(loopStepEntity, loopResults.errors.length === 0, this.formatLoopErrors(loopResults.errors), loopResults);
+        // Inject before the early return below: a Loop agent re-prompts after a Failed step, and the
+        // loop-results message (the condition error, under Errors) is the only way the model learns why.
         if (this.AgentTypeInstance.InjectLoopResultsAsMessage) {
             this.injectLoopResultsMessage('While', whileOp.condition, loopResults.results, loopResults.errors, params, whileOp.action?.name);
         }
+        // A condition that never evaluated means the loop never ran: fail the step rather than
+        // report a completed zero-iteration loop.
+        if (loopResults.conditionError && loopResults.iterations === 0) {
+            return this.createFailedStep(loopResults.conditionError, previousDecision);
+        }
+        const retryInstructions = loopResults.conditionError
+            ? `While loop request using condition '${whileOp.condition}' stopped after ${loopResults.iterations} iteration(s): ${loopResults.conditionError}`
+            : `Completed While loop request using condition '${whileOp.condition}' after ${loopResults.iterations} iteration(s)`;
         return {
             step: 'Retry',
-            retryInstructions: `Completed While loop request using condition '${whileOp.condition}' after ${loopResults.iterations} iteration(s)`,
+            retryInstructions,
             terminate: false,
             newPayload: loopResults.finalPayload,
             previousPayload: previousDecision.previousPayload
@@ -11927,7 +12757,7 @@ The context is now within limits. Please retry your request with the recovered c
         }
         // Also promote any media from the final step's promoteMediaOutputs
         if (finalStep.promoteMediaOutputs && finalStep.promoteMediaOutputs.length > 0) {
-            this.promoteMediaOutputs(finalStep.promoteMediaOutputs);
+            this.PromoteMediaOutputs(finalStep.promoteMediaOutputs);
         }
         // Return unified media outputs — all items are persisted by AgentRunner.
         // Sub-agents pass their mediaOutputs to parent for merging and placeholder resolution.
@@ -12170,7 +13000,7 @@ The context is now within limits. Please retry your request with the recovered c
             if (item.message.role === 'tool') {
                 // compact per block so the tool turn keeps answering its call.
                 const limit = item.metadata.compactLength || 500;
-                const compactedTurn = compactToolResultContent(item.message, (t) => (t.length > limit ? `${t.slice(0, limit)}… [compacted from ${t.length} chars]` : t));
+                const compactedTurn = CompactToolResultContent(item.message, (t) => (t.length > limit ? `${t.slice(0, limit)}… [compacted from ${t.length} chars]` : t));
                 const saved = this.estimateTokens(originalContent) - this.estimateTokens(compactedTurn.content);
                 params.conversationMessages[item.index] = {
                     ...compactedTurn,
@@ -12270,10 +13100,12 @@ The context is now within limits. Please retry your request with the recovered c
      * (agent or type ContextWindowMaxTokens) — before the first prompt the model is
      * unknown, and compacting against the conservative default would over-trigger on
      * large-context models. The post-turn hook (real model known) covers those.
+     * Skipped under a history floor (`ConversationHistoryFrom`): a summary folds in the
+     * conversation from its first message, which is what the floor excludes.
      * @protected
      */
     async checkPreTurnCompaction(params, config) {
-        if (!params.conversationId || this._depth !== 0) {
+        if (!params.conversationId || this._depth !== 0 || params.ConversationHistoryFrom) {
             return;
         }
         const budget = this.resolveCompactionBudget(params, config);
@@ -12298,10 +13130,19 @@ The context is now within limits. Please retry your request with the recovered c
      * final step (→ AwaitingFeedback) is the NORMAL ending of a conversational turn;
      * gating on 'Completed' alone silently disabled post-turn compaction for exactly
      * the long-chat scenario this feature targets.
+     *
+     * Skipped under a history floor (`ConversationHistoryFrom`). A run with a floor must not
+     * write the conversation's summary: the summary covers every row below its boundary, and
+     * a run that may not read the rows before the floor can't produce that — nor, once reads
+     * are narrowed to what the asker can see, can it tell which rows it was not shown.
      * @protected
      */
     startPostTurnCompaction() {
         const params = this._executeParams;
+        if (params?.ConversationHistoryFrom) {
+            this.logStatus('Post-turn compaction skipped — the run has a history floor', true, params);
+            return;
+        }
         if (!params?.conversationId || this._depth !== 0 || !this._agentRun
             || !BaseAgent.settledRunStatuses.includes(this._agentRun.Status)) {
             // A quiet return here is indistinguishable from "the pass ran and found nothing to do":
@@ -12570,6 +13411,11 @@ The context is now within limits. Please retry your request with the recovered c
                     };
                     promptParams.contextUser = params.contextUser;
                     promptParams.agentId = params.agent.ID;
+                    promptParams.UserID = ResolvePromptRunUserID({
+                        UserID: params.userId,
+                        AgentRun: this._agentRun,
+                        ContextUser: params.contextUser,
+                    }) ?? undefined;
                     const runner = new AIPromptRunner();
                     const result = await runner.ExecutePrompt(promptParams);
                     // Update step with result