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

package/dist/base-agent.d.ts

@@ -10,9 +10,9 @@
  * @author MemberJunction.com
  * @since 2.49.0
  */
-import { MJAIAgentTypeEntity, MJTemplateParamEntity, MJAIAgentRelationshipEntity, MJAIAgentNoteEntity, MJAIAgentExampleEntity, MJAISkillEntity } from '@memberjunction/core-entities';
+import { MJAIAgentTypeEntity, MJTemplateParamEntity, MJAIAgentRelationshipEntity, MJAIAgentNoteEntity, MJAIAgentExampleEntity, MJAISkillEntity, MJAIVendorEntity } from '@memberjunction/core-entities';
 import { type NativeToolBinding } from './native-tools/control-tools.js';
-import { MJAIAgentRunEntityExtended, MJAIAgentRunStepEntityExtended, MJAIPromptEntityExtended, MJAIAgentEntityExtended, MJAIPromptRunEntityExtended } from "@memberjunction/ai-core-plus";
+import { MJAIAgentRunEntityExtended, MJAIAgentRunStepEntityExtended, MJAIPromptEntityExtended, MJAIAgentEntityExtended, MJAIModelEntityExtended, MJAIPromptRunEntityExtended } from "@memberjunction/ai-core-plus";
 import { UserInfo, IMetadataProvider } from '@memberjunction/core';
 import { ChatMessage, ChatMessageContent, BaseRealtimeModel, IRealtimeSession, ChatToolChoice } from '@memberjunction/ai';
 import { BaseAgentType } from './agent-types/base-agent-type.js';
@@ -26,6 +26,7 @@ import { CarryForwardStepRecord } from './tool-result-format.js';
 import { AgentPreExecutionRAGResult } from './agent-pre-execution-rag.js';
 import { AIPromptParams, AIPromptRunResult, ExecuteAgentParams, AgentConfiguration, ExecuteAgentResult, AgentAction, AgentSubAgentRequest, BaseAgentNextStep, MessageLifecycleEvent, AgentChatMessage, AgentChatMessageMetadata, AIModelSelectionInfo, ActionChange, ActionChangeScope, SubAgentChange, MediaOutput, FileOutputRef, SecondaryScopeConfig, SecondaryScopeValue, AgentResponseForm, AgentPipelineRequest, AgentSkillActivationRequest, AgentSkillInvocation, SkillAvailabilityPurpose } from '@memberjunction/ai-core-plus';
 import { MJActionEntityExtended, ActionResult, ActionParam, AIDirective } from '@memberjunction/actions-base';
+import { RuntimeStateDateTime, RuntimeStateScratchpad } from './runtime-state-fragment.js';
 import { ArtifactToolCall, StoredToolResult } from './ArtifactToolManager.js';
 import { MemoryWriteRequest, MemoryWriteResult } from './MemoryWriteManager.js';
 import { PipelineToolRegistry, PipelineExecutionResult } from './pipeline/index.js';
@@ -40,6 +41,8 @@ interface ActionResultSummary {
     resultCode: string;
     message: string;
     aiDirectives?: AIDirective[];
+    /** Set when the circuit breaker blocked the call without dispatching it. */
+    breakerReason?: ActionCircuitBreakerReason;
 }
 /**
  * Resolved per-run configuration for structurally compressing inline action-result
@@ -58,6 +61,47 @@ export interface ActionResultCrushConfig {
      */
     codeLang: CodeLang | undefined;
 }
+/**
+ * Options for {@link BaseAgent.ExecuteSingleAction}.
+ */
+export interface ExecuteSingleActionOptions {
+    /**
+     * When true, the run-scoped action circuit breaker is bypassed for this call: none of the
+     * pre-execution checks (fatal lockout, identical-arguments rule, consecutive-attempt budget)
+     * apply, and the outcome neither increments nor resets the failure history.
+     *
+     * Set by the pipeline registry and by the ForEach / While iteration paths. Those callers do
+     * their own per-element failure accounting and expect elements to be independent, and there
+     * is no model in the loop to act on the breaker's guidance, so counting those calls would let
+     * a run of bad elements block the rest of the batch and then block the model's next direct
+     * call too.
+     */
+    skipCircuitBreaker?: boolean;
+}
+/**
+ * Which circuit-breaker rule blocked an action call without dispatching it.
+ *
+ * - `'fatal'` — the action failed earlier in the run with a configuration or credential error and is
+ *   locked out for the rest of the run.
+ * - `'identical-arguments'` — the action already failed {@link IDENTICAL_FAILURE_THRESHOLD} times
+ *   with these exact arguments.
+ * - `'attempts-exhausted'` — the action has failed {@link ACTION_FAILURE_BUDGET} consecutive times
+ *   across any arguments.
+ */
+export type ActionCircuitBreakerReason = 'fatal' | 'identical-arguments' | 'attempts-exhausted';
+/** Identical-arguments rule: this many failures with the same arguments block further identical calls. */
+export declare const IDENTICAL_FAILURE_THRESHOLD = 2;
+/** Attempt budget: this many consecutive failures, across any arguments, disable the action for the run. */
+export declare 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 declare class CircuitBreakerActionResult extends ActionResult {
+    readonly Reason: ActionCircuitBreakerReason;
+    constructor(Reason: ActionCircuitBreakerReason);
+}
 /**
  * The agent-invariant "base" catalog cached (process-wide) on AIEngine and reused across runs/steps.
  * Holds the resolved sub-agents + actions and their formatted markdown, plus the base merged
@@ -148,6 +192,138 @@ export declare class BaseAgent {
      * @private
      */
     private _lastModelSelectionInfo;
+    /**
+     * The volatile runtime state message generated for the most recent prompt execution.
+     * When append-only trailing state mode is used (e.g. OpenAI prompt caching), this fragment
+     * is retained in conversation history across turns to preserve a byte-exact prompt prefix.
+     * @private
+     */
+    private _lastVolatileStateMessage;
+    /**
+     * The trailing-state retention mode once it has been decided for this run, frozen at the first
+     * model selection so the layout never flips again mid-run. Undefined until then (turn 1 only).
+     * @private
+     */
+    private _resolvedTrailingStateMode;
+    /**
+     * 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
+     */
+    private _turn1InsertionIndex;
+    /**
+     * 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
+     */
+    private _fatalActionFailures;
+    /**
+     * 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
+     */
+    private _actionFailureHistory;
+    /**
+     * 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.
+     */
+    protected normalizeActionParams(params: Record<string, unknown> | null | undefined): string;
+    /**
+     * 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.
+     */
+    protected normalizeActionParamEntry(key: string, value: unknown): {
+        key: string;
+        value: unknown;
+    } | null;
+    /**
+     * 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.
+     */
+    protected normalizeActionParamValue(value: unknown): unknown;
+    /**
+     * 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.
+     */
+    protected isFatalActionError(message: string | null | undefined, actionParams?: Record<string, unknown> | null): boolean;
+    /**
+     * 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.
+     */
+    protected hasCredentialShapedArguments(actionParams?: Record<string, unknown> | null): boolean;
+    /**
+     * 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.
+     */
+    protected recordActionFailure(action: AgentAction, actionEntity: MJActionEntityExtended | undefined, message: string | null | undefined, normalizedParams: string): void;
+    /**
+     * Clears the parameter-aware failure history for an action after it succeeds, so the
+     * identical-arguments rule and the consecutive-attempt budget start over.
+     */
+    protected clearActionFailureRecord(action: AgentAction, actionEntity: MJActionEntityExtended | undefined): void;
+    /**
+     * 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.
+     */
+    protected checkActionCircuitBreaker(params: ExecuteAgentParams, action: AgentAction, actionEntity: MJActionEntityExtended, normalizedParams: string): CircuitBreakerActionResult | null;
+    /** The failed {@link ActionResult} a blocked call returns in place of dispatching. */
+    protected buildBlockedActionResult(actionEntity: MJActionEntityExtended, reason: ActionCircuitBreakerReason, message: string): CircuitBreakerActionResult;
+    /**
+     * 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.
+     */
+    protected classifyActionFailure(summary: ActionResultSummary): ActionCircuitBreakerReason | 'warning';
+    /** The guidance line appended to the history for one failed action. */
+    protected formatActionFailureDirective(summary: ActionResultSummary): string;
     /**
      * Returns the active metadata provider for this agent run. Subclasses MUST
      * use this getter (rather than `new Metadata()` or `Metadata.Provider`) so
@@ -300,6 +476,8 @@ export declare class BaseAgent {
      * }]);
      * ```
      */
+    PromoteMediaOutputs(mediaOutputs: MediaOutput[]): void;
+    /** @deprecated Use {@link PromoteMediaOutputs}. */
     promoteMediaOutputs(mediaOutputs: MediaOutput[]): void;
     /**
      * Gets the currently accumulated media outputs for this agent run.
@@ -1384,6 +1562,151 @@ export declare class BaseAgent {
      */
     protected isFinalPermittedIteration(params: ExecuteAgentParams): boolean;
     protected preparePromptParams<P>(config: AgentConfiguration, payload: P, params: ExecuteAgentParams): Promise<AIPromptParams>;
+    /**
+     * 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.
+     */
+    protected restoreTurn1VolatileStateIfNeeded(params: ExecuteAgentParams, isAppendOnly: boolean): void;
+    /**
+     * 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.
+     */
+    protected runHasVolatileStateMessage(params: ExecuteAgentParams): boolean;
+    /**
+     * 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.
+     */
+    protected assembleOutgoingMessages(history: ChatMessage[], fragment: AgentChatMessage, isAppendOnly?: boolean): ChatMessage[];
+    /**
+     * 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.
+     */
+    protected shouldUseAppendOnlyTrailingState(promptParams: AIPromptParams): boolean;
+    /**
+     * 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.
+     */
+    protected resolvePrefixPromptCache(model: MJAIModelEntityExtended | undefined, vendor: MJAIVendorEntity | undefined): boolean;
+    /**
+     * 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.
+     */
+    protected buildVolatileStateMessage<P>(params: ExecuteAgentParams, promptParams: AIPromptParams, payload: P, childPrompt: MJAIPromptEntityExtended | undefined, agentType: MJAIAgentTypeEntity, systemPrompt?: MJAIPromptEntityExtended): Promise<AgentChatMessage | null>;
+    /**
+     * 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.
+     */
+    protected resolveRelocatedSpecialization(promptParams: AIPromptParams, childPrompt: MJAIPromptEntityExtended | undefined, agentType: MJAIAgentTypeEntity, contextUser: UserInfo): Promise<string | null>;
+    /**
+     * 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.
+     */
+    protected resolveRuntimeStateDelivery(systemPrompt: MJAIPromptEntityExtended | undefined, contextUser: UserInfo): Promise<'trailing' | 'embedded' | 'unsupported' | 'unknown'>;
+    /**
+     * 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.
+     */
+    protected get volatileTemplateMarkers(): readonly string[];
+    /**
+     * True when unrendered template text contains any of {@link volatileTemplateMarkers} — the legacy
+     * Loop layout, or any template that embeds the payload.
+     */
+    protected templateTextEmbedsVolatileState(templateText: string): boolean;
+    /**
+     * 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.
+     */
+    protected loadPromptTemplateText(prompt: MJAIPromptEntityExtended | undefined, contextUser: UserInfo): Promise<string | 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.
+     */
+    protected loadChildPromptTemplateText(childPrompt: MJAIPromptEntityExtended, contextUser: UserInfo): Promise<string | null>;
+    /**
+     * 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.
+     */
+    protected resolveFragmentDateTime(promptParams: AIPromptParams): Promise<RuntimeStateDateTime | null>;
+    /**
+     * 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.
+     */
+    protected readScratchpadFromTemplateData(data: Record<string, unknown>): RuntimeStateScratchpad | null;
     /**
      * Executes the configured prompt. Always uses the attemptJSONRepair option to try to fix LLM
      * JSON syntax issues if they arise.
@@ -1624,6 +1947,32 @@ export declare class BaseAgent {
      * @protected
      */
     protected serializePayloadAtEnd(payload: any): string | 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
+     */
+    protected recoveryStrategy_DropStaleVolatileState(params: ExecuteAgentParams, tokensToSave: number, currentStepCount: number): {
+        tokensSaved: number;
+        strategyName: string;
+    };
     /**
      * Recovery Strategy 1: Remove oldest tool-result messages.
      * Targets messages older than minAge turns for removal.
@@ -1728,6 +2077,8 @@ export declare class BaseAgent {
      * 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
      */
     protected injectPriorTurnToolResults(params: ExecuteAgentParams): Promise<void>;
@@ -2051,6 +2402,20 @@ export declare class BaseAgent {
      * @since 2.131.0
      */
     protected extractSchemaDefaults(schemaJson: string | null | undefined): Record<string, unknown>;
+    /**
+     * 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.
+     */
+    protected actionMayUseRuntimeAPIKey(action: MJActionEntityExtended, driverClass: string, params: ExecuteAgentParams): boolean;
+    /**
+     * 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.
+     */
+    private buildRuntimeAPIKeyResolver;
     /**
      * 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,
@@ -2059,12 +2424,14 @@ export declare class BaseAgent {
      * @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
      */
-    ExecuteSingleAction(params: ExecuteAgentParams, action: AgentAction, actionEntity: MJActionEntityExtended, contextUser?: UserInfo): Promise<ActionResult>;
+    ExecuteSingleAction(params: ExecuteAgentParams, action: AgentAction, actionEntity: MJActionEntityExtended, contextUser?: UserInfo, options?: ExecuteSingleActionOptions): Promise<ActionResult>;
     /**
      * Makes a SLICED conversation window safe to send on its own.
      *
@@ -2095,6 +2462,13 @@ export declare class BaseAgent {
      * **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).
      *
@@ -2847,6 +3221,13 @@ export declare class BaseAgent {
      * 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.
+     */
+    protected actionOptionsForAgentType(): ExecuteSingleActionOptions | undefined;
     /**
      * Executes actions step and tracks it.
      *
@@ -3280,6 +3661,23 @@ export declare class BaseAgent {
      * rather than being deleted after a single prompt turn.
      */
     private injectLoopResultsMessage;
+    /**
+     * 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.
+     */
+    private failLoopBeforeFirstIteration;
+    /**
+     * 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).
+     */
+    private describeLoopError;
+    /** All loop errors as text for a step's ErrorMessage. */
+    private formatLoopErrors;
     /**
      * Formats loop iteration results as markdown. Handles two distinct result shapes
      * depending on whether the loop body executed actions or sub-agents:
@@ -3442,6 +3840,8 @@ export declare class BaseAgent {
      * (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
      */
     protected checkPreTurnCompaction(params: ExecuteAgentParams, config: AgentConfiguration | undefined): Promise<void>;
@@ -3453,6 +3853,11 @@ export declare class BaseAgent {
      * 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
      */
     protected startPostTurnCompaction(): void;