@memberjunction/ai-agents 6.2.0-edge.2 → 6.2.0-edge.4

package/dist/base-agent.d.ts

@@ -10,7 +10,7 @@
  * @author MemberJunction.com
  * @since 2.49.0
  */
-import { MJAIAgentTypeEntity, MJTemplateParamEntity, MJAIAgentRelationshipEntity, MJAIAgentNoteEntity, MJAIAgentExampleEntity, MJAISkillEntity, MJAIVendorEntity } from '@memberjunction/core-entities';
+import { MJAIAgentTypeEntity, MJTemplateParamEntity, MJAIAgentRelationshipEntity, MJAIAgentNoteEntity, MJAIAgentExampleEntity, MJAISkillEntity, MJAIVendorEntity, type ConversationBranchRow } from '@memberjunction/core-entities';
 import { type NativeToolBinding } from './native-tools/control-tools.js';
 import { MJAIAgentRunEntityExtended, MJAIAgentRunStepEntityExtended, MJAIPromptEntityExtended, MJAIAgentEntityExtended, MJAIModelEntityExtended, MJAIPromptRunEntityExtended } from "@memberjunction/ai-core-plus";
 import { UserInfo, IMetadataProvider } from '@memberjunction/core';
@@ -24,9 +24,9 @@ import { AIEngine } from '@memberjunction/aiengine';
 import { AgentMemoryObservability } from './agent-memory-context-builder.js';
 import { CompactionOutcome, EffectiveContextBudget } from './ConversationCompactionManager.js';
 import { ConversationToolCall, ConversationToolExecutionResult, ConversationToolSummaryHost } from './ConversationToolManager.js';
-import { CarryForwardStepRecord } from './tool-result-format.js';
+import { CarryForwardStepRecord, StoppedRunStepRecord } 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, AgentDecisionRequest, AgentDecisionResult, AgentDecisionAnswerSummary } from '@memberjunction/ai-core-plus';
+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, AgentDecisionRequest, AgentDecisionResult, AgentDecisionAnswerSummary, StopContinuationMode } 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';
@@ -37,6 +37,21 @@ import { PipelineToolRegistry, PipelineExecutionResult } from './pipeline/index.
  * Compact representation of a single action's execution result, used for
  * building the markdown summary that goes into conversation messages.
  */
+/**
+ * A stopped run's step with its outcome. The full-stack resume reads every step of the run, not
+ * only completed results: it needs the prompt steps' recorded message stacks, and it needs to
+ * know which requested actions finished before the stop.
+ */
+export interface StoppedRunStackStepRecord extends StoppedRunStepRecord {
+    Status: MJAIAgentRunStepEntityExtended['Status'];
+    Success: MJAIAgentRunStepEntityExtended['Success'];
+}
+/** What the pre-execution phase loaded about a user-stopped predecessor, applied once the phase settles. */
+interface StoppedRunContinuation {
+    RunID: string;
+    Mode: StopContinuationMode;
+    Steps: StoppedRunStackStepRecord[];
+}
 interface ActionResultSummary {
     actionName: string;
     success: boolean;
@@ -388,6 +403,19 @@ export declare class BaseAgent {
      */
     protected static readonly DEFAULT_ABSOLUTE_MAX_ITERATIONS = 5000;
     private _agentRun;
+    /**
+     * The prefix of the abort reason the wall-clock guard in {@link Execute} raises when a run
+     * outlives `maxExecutionTimeMs`. The guard appends the agent and the budget after it; a reader
+     * ({@link CancellationReasonForAbort}) checks the prefix, never the wording after it.
+     */
+    static readonly AgentTimeoutAbortReason = "Agent execution exceeded maxExecutionTimeMs";
+    /**
+     * The abort controller that governs the current `Execute` call (the merged timeout/upstream
+     * signal). Held so {@link initializeAgentRun} can register it with the watchdog's stop relay:
+     * when someone marks this run's row `Cancelled`, the watchdog aborts it and the loop's
+     * existing cancellation checks end the run. Null outside an execution.
+     */
+    private _runAbortController;
     /**
      * The task graph this run submitted and is now waiting on, or null.
      *
@@ -677,6 +705,11 @@ export declare class BaseAgent {
      * Armed only when the run has a conversationId (the cross-turn context gate).
      */
     private _conversationToolManager;
+    /**
+     * The conversation's branch rows for the current run, loaded once when the run is on a
+     * branch (`ExecuteAgentParams.ConversationBranchID`). Empty on the trunk.
+     */
+    private _conversationBranches;
     /**
      * Manages in-flight durable memory writes for the current agent run.
      * Only consulted when the agent has AllowMemoryWrite enabled.
@@ -719,6 +752,12 @@ export declare class BaseAgent {
      * @private
      */
     private _openingRequest;
+    /**
+     * The run's {@link AIPromptExecutionScope}, recorded when the run starts, for decision calls made
+     * from helpers that are not handed the run's params (discovery, catalog narrowing).
+     * @private
+     */
+    private _runExecutionScope;
     /**
      * Whether the run answers its conversation's opening request ({@link IsOpeningTurn}), read from
      * the messages it started with. Decision discovery asks about no other turn.
@@ -1047,7 +1086,8 @@ export declare class BaseAgent {
      * without provider SDKs or DB metadata.
      *
      * Production resolution: pick the highest-power active model of AIModelType `Realtime`; then
-     * pick its highest-priority active vendor whose `DriverClass` has a resolvable API key; then
+     * pick its highest-priority active vendor whose `DriverClass` has a resolvable API key, unless another keyed
+     * vendor matches whether the run will show an avatar better ({@link ChooseRealtimeVendorForAvatar}); then
      * instantiate the driver via the `ClassFactory`. Returns `null` (never throws) if any step
      * can't be satisfied — the caller turns that into a clean FAILED result. (Per-agent realtime
      * model preference can later be wired through the agent's prompt-model config, the same path
@@ -1064,6 +1104,19 @@ export declare class BaseAgent {
         apiName: string;
         driverClass?: string;
     } | null>;
+    /**
+     * Whether a session-driven run will show an avatar: the agent's video setting is on and the run could show one
+     * ({@link RealtimeSessionCanShowAvatar}) — a server-side session, so only when its host publishes the avatar into a
+     * room (`params.data.realtimeAvatarDelivery` `'room'`) and it is not a phone call (`params.data.realtimePhoneCall`).
+     *
+     * @param params The execution parameters.
+     */
+    private realtimeRunShowsAvatar;
+    /**
+     * A vendor's realtime driver on its key, with the model and vendor identifiers a run resolves to; `null` when the
+     * key or the driver is missing.
+     */
+    private instantiateRealtimeRunVendor;
     /**
      * The active `Realtime`-AIModelType models to try, in resolution order — the candidate list
      * {@link resolveRealtimeModel} walks until one yields a usable vendor + key + driver. Returns ALL
@@ -1668,15 +1721,22 @@ export declare class BaseAgent {
     /**
      * The `tool_choice` for this turn (§8.3).
      *
-     * `'auto'` normally, `'none'` on the last turn this run will be allowed.
+     * `'auto'` normally; on the last turn this run will be allowed, a forced `complete_task` call.
      *
      * **Why the final turn is special.** A tool call is a request to continue: the framework runs
      * the action, feeds the result back, and the model decides again. On the last permitted
      * iteration there is no "again" — the limit check fires the moment the turn returns, so the
      * action is executed, paid for, and its result discarded, and the run ends with no answer for
      * the user because the model spent its last turn asking a question instead of answering one.
-     * Forcing `'none'` converts that turn into what the framework actually needs from it: a
-     * terminal envelope.
+     * The final turn is forced to what the framework actually needs from it: a terminal answer.
+     *
+     * **Why `complete_task` and not `'none'`.** Under implicit control flow, `'none'` forbids the
+     * model's only way to store its result — `payload_change_request` and `complete_task` are tools
+     * too — so a forced `'none'` turn can end the run but never deliver the payload. Naming
+     * `complete_task` forces the one call that does both. A model that is NOT on implicit control
+     * flow never receives `complete_task` (the runner strips control tools), and the runner then
+     * downgrades the named choice to `'none'`: the envelope turn the hybrid needs. Providers also
+     * enforce a named choice more reliably than `'none'`.
      *
      * **What this does NOT fix.** Models call a tool on a measurable share of turns whose right
      * answer was chat, completion or delegation. Those are not predictable
@@ -1684,11 +1744,11 @@ export declare class BaseAgent {
      * address them. That belongs to the prompt, and is why the native-mode Actions section names
      * the cases explicitly.
      *
-     * Subclasses may narrow this further; the base contract is that a forced `'none'` must never be
-     * relaxed to `'auto'` on a turn the framework has already decided is terminal.
+     * Subclasses may narrow this further; the base contract is that a forced terminal choice must
+     * never be relaxed to `'auto'` on a turn the framework has already decided is terminal.
      *
      * @param params The run parameters, for the per-run iteration override
-     * @returns `'none'` on the final permitted iteration, otherwise `'auto'`
+     * @returns `{ name: 'complete_task' }` on the final permitted iteration, otherwise `'auto'`
      */
     protected resolveToolChoiceForTurn(params: ExecuteAgentParams): ChatToolChoice;
     /**
@@ -2063,7 +2123,8 @@ export declare class BaseAgent {
     };
     /**
      * Converts ChatMessageContent to a string representation.
-     * Handles both simple strings and content block arrays.
+     * Handles both simple strings and content block arrays. Text blocks keep their text;
+     * image, audio, video and file blocks become a short stub instead of their base64.
      *
      * @param content - The message content to convert
      * @returns String representation of the content
@@ -2208,6 +2269,8 @@ export declare class BaseAgent {
      * @protected
      */
     protected processNextStep<P>(nextStep: BaseAgentNextStep<P>, params: ExecuteAgentParams, agentType: MJAIAgentTypeEntity, promptResult: AIPromptRunResult, currentPayload: P, currentStep: MJAIAgentRunStepEntityExtended): Promise<BaseAgentNextStep<P>>;
+    /** The tool name the model used for a call on this turn — `payload_change_request` when it cannot be found. */
+    private nativeToolNameForCall;
     /**
      * Executes a batch of artifact tool calls, recording each as its own
      * `Tool` AIAgentRunStep (a sibling of the Prompt step that requested them)
@@ -2237,6 +2300,174 @@ export declare class BaseAgent {
      * @protected
      */
     protected injectPriorTurnToolResults(params: ExecuteAgentParams): Promise<void>;
+    /**
+     * Carries a STOPPED previous turn's completed results forward into this run's context.
+     *
+     * {@link injectPriorTurnToolResults} covers the normal case: the previous run settled and
+     * its inline tool results ride along one turn. A run the user stopped never settles, so
+     * that path skips it, and the next turn would redo every action the stopped run had already
+     * finished (observed: a stopped Sage run had five weather lookups and fifteen searches done;
+     * "keep going" redid all of them). This path looks at the newest root run for this agent in
+     * the conversation and, when it is one the user stopped, carries it forward per
+     * {@link ExecuteAgentParams.stopContinuationMode}: by default its own message stack is resumed
+     * so the agent picks up where it stopped; in summary mode its completed Actions and Tool results
+     * go in as one transient message that says to continue, not restart. A settled newest run means
+     * the normal path already has the context, so nothing is added here. During execution the two
+     * halves run separately: {@link loadStoppedRunContinuation} in the parallel phase, then
+     * {@link applyStoppedRunContinuation} once it settles.
+     *
+     * Same gates as the sibling: root depth, a conversation, no history floor. Fail-soft.
+     * @protected
+     */
+    protected injectStoppedRunResults(params: ExecuteAgentParams): Promise<void>;
+    /**
+     * The I/O half of {@link injectStoppedRunResults}: finds a user-stopped predecessor and loads its
+     * steps (every step for the full-stack resume, only completed results for the summary). Runs inside
+     * the pre-execution parallel phase; nothing here touches the message list.
+     * @protected
+     */
+    protected loadStoppedRunContinuation(params: ExecuteAgentParams): Promise<StoppedRunContinuation | null>;
+    /**
+     * The message half of {@link injectStoppedRunResults}, applied once the pre-execution phase has
+     * settled so it never races the memory and RAG injections running beside the load.
+     *
+     * Full stack: the stopped run's own turns are spliced in ahead of the user's new message, in the
+     * shape the loop built while running, so the agent resumes where it stopped. When the stack cannot
+     * be resumed (no recorded prompt, or its anchor is missing) this falls back to the summary.
+     * Summary: the completed results go in as one carried-forward message. Fail-soft.
+     * @protected
+     */
+    protected applyStoppedRunContinuation(params: ExecuteAgentParams, continuation: StoppedRunContinuation | null, continuationMessage: ChatMessage | undefined): void;
+    /**
+     * The full-stack half of {@link applyStoppedRunContinuation}: true when the stopped run's turns were
+     * spliced in. Any failure leaves the messages untouched and returns false, so the caller carries
+     * the results as a summary instead of losing them.
+     * @private
+     */
+    private tryResumeStoppedRunStack;
+    /** The mode a run uses when the caller does not set {@link ExecuteAgentParams.stopContinuationMode}. */
+    static readonly DefaultStopContinuationMode: StopContinuationMode;
+    /**
+     * Placed just before the user's new message when a stopped run's stack is resumed, so the model
+     * knows the turns above it were interrupted and what follows is how to continue.
+     */
+    static readonly StoppedRunResumeNotice = "[Note: The user stopped the previous execution at this point. The instruction that follows is the continuation request.]";
+    /** Result code and message for an action the stopped run requested but never ran. */
+    private static readonly stoppedBeforeRunResultCode;
+    private static readonly stoppedBeforeRunMessage;
+    /**
+     * The stopped run's turns in the shape the loop builds, or null when they cannot be recovered.
+     *
+     * The last prompt step recorded the run's whole message stack as it went into that prompt; the
+     * first prompt step recorded the stack the run started from (history plus this run's injections,
+     * which the new run adds for itself). The difference is the run's own turns. If the last prompt
+     * completed, its decision and the steps after it are rebuilt with the loop's own builders.
+     * @protected
+     */
+    protected buildResumedStoppedRunTurns(steps: StoppedRunStackStepRecord[], params: ExecuteAgentParams): AgentChatMessage[] | null;
+    /**
+     * The run's own turns: what follows the run's starting message in its last recorded stack, minus
+     * the per-request runtime-state fragments (the new run appends its own). The starting message is
+     * matched at its original position first, so a repeated message earlier in the history ("keep
+     * going" twice) cannot be mistaken for it. Null when it cannot be found.
+     */
+    static ExtractStoppedRunLoopTurns(firstStack: AgentChatMessage[] | null, lastStack: AgentChatMessage[] | null): AgentChatMessage[] | null;
+    /**
+     * Inserts resumed turns ahead of the user's new message (and ahead of the stopped run's own reply
+     * to the user, when that sits right before it), followed by {@link StoppedRunResumeNotice}. The new
+     * message is found by identity, captured before the pre-execution phase added anything. Returns
+     * false, changing nothing, when it is not a user message still in the list.
+     */
+    static SpliceResumedTurns(messages: ChatMessage[], resumed: AgentChatMessage[], continuationMessage: ChatMessage | undefined): boolean;
+    /**
+     * What the stopped run's last completed prompt decided, rebuilt as the loop would have written it:
+     * the model's native call turn when results go back natively, the invocation record and the results
+     * of the actions that finished (and a not-executed result for the ones that did not) for an Actions
+     * turn, otherwise the completed results as a carried-forward message. Any native call left without
+     * a result is then answered, so the history is valid for every provider.
+     * @protected
+     */
+    protected buildStoppedRunTail(decision: BaseAgentNextStep | null, tailSteps: StoppedRunStackStepRecord[], params: ExecuteAgentParams): AgentChatMessage[];
+    /** One result per requested action, in request order: its completed step's result, or not executed. @private */
+    private summarizeStoppedRunActions;
+    /**
+     * A completed action step as the loop summarizes a live action result: output parameters only,
+     * with large media swapped for placeholders. Null when the step's output cannot be read.
+     * @private
+     */
+    private summarizeStoppedActionStep;
+    /** The message stack a prompt step recorded as its input, or null. @private */
+    private static readPromptStepStack;
+    /** The decision a completed prompt step recorded, or null. @private */
+    private static readPromptStepDecision;
+    /** The action an Actions step ran, from its recorded input, or null. @private */
+    private static readStoppedActionName;
+    /**
+     * A resumed turn re-dated to this run's first turn. The stopped run's turn numbers mean nothing
+     * to this run's counter, and expiry compares the two, so a resumed result ages from now.
+     * @private
+     */
+    private static restampResumedTurn;
+    /** A step whose result the summary carries: a completed, successful Actions or Tool step. @private */
+    private static isCarriedForwardResultStep;
+    /**
+     * A carried-forward results message: a user-role message that expires after two turns and
+     * compacts to its head, so results reused once never compound across the conversation. Shared
+     * by the settled-run and stopped-run carry-forwards so the two cannot age differently.
+     * @private
+     */
+    private buildCarryForwardMessage;
+    /**
+     * The ID of this agent's newest root run on this turn's branch path IF the user stopped it,
+     * else null. One query over the runs that could be the predecessor (settled, or stopped by
+     * the user): the newest decides. A stopped run older than a settled one is history the
+     * settled run already built on, so it is not carried again. The path scopes it the same way
+     * as {@link loadPriorTurnToolResultSteps}: a run stopped on a sibling branch is never resumed.
+     * @private
+     */
+    private findUserStoppedPredecessorRunId;
+    /**
+     * `runId` if that run is one the user stopped, else null. The chained-run counterpart of
+     * {@link findUserStoppedPredecessorRunId}: one primary-key read of the named run instead of a
+     * search of the conversation, so a run the resolver already resolved is not looked up twice,
+     * and a run chained to a settled predecessor (an ordinary continuation) resumes nothing.
+     * @private
+     */
+    private userStoppedRunIdIfStopped;
+    /**
+     * Every step of a stopped run, in step order: the full-stack resume reads the prompt steps'
+     * recorded stacks and which requested actions completed. Read from the database, since the run
+     * was stopped moments ago.
+     * @private
+     */
+    private loadStoppedRunStack;
+    /** The completed, successful Actions and Tool steps of a stopped run, in step order. @private */
+    private loadStoppedRunResultSteps;
+    /**
+     * Budget for the stopped-run carry-forward message. Smaller than a standalone tool result on
+     * purpose: this rides at the front of a continuation turn's context, and a stopped run can
+     * hold dozens of search results. ~7k tokens keeps the useful values and drops the long tails.
+     */
+    protected static readonly maxStoppedRunResultChars = 28000;
+    /**
+     * Renders a stopped run's completed step results into the carried-forward message body.
+     * Pure and static for testability. An Actions step renders as the action call (name and
+     * params) with its output parameters, or its message when it produced none; a Tool step
+     * renders under the same contract as {@link BuildPriorTurnToolResultsMessage}. Failed or
+     * unparseable steps are skipped. Each section is capped at an even share of `maxChars`
+     * (never below a readable floor) and the whole body at `maxChars`, with a note for anything
+     * dropped. Returns null when nothing usable remains.
+     */
+    static BuildStoppedRunResultsMessage(steps: ReadonlyArray<StoppedRunStepRecord>, maxChars: number): string | null;
+    /** One stopped-run step as a result section, or null when it carries nothing reusable. @private */
+    private static renderStoppedRunStep;
+    /**
+     * The `MJ: AI Agent Runs` predicate for this agent's previous settled root run on one
+     * branch path: the run's reply row must be on that path, so a run made on a sibling
+     * branch is never carried forward, and not replaced by a rerun of its turn, so a replaced
+     * answer's tool results are never carried forward.
+     */
+    static BuildPriorTurnRunFilter(conversationId: string, agentId: string, branchId: string | null, branches: ReadonlyArray<ConversationBranchRow>, statusList: string): string;
     /**
      * Loads this agent's previous settled root run's Tool steps for this conversation
      * (settled = {@link settledRunStatuses}: Completed or AwaitingFeedback).
@@ -2259,9 +2490,11 @@ export declare class BaseAgent {
      * only when the run row settled as {@link settledRunStatuses} (Completed OR
      * AwaitingFeedback — the normal chat-turn ending) — a failed run leaves the previous
      * settled run's entry standing, just as the RunView filter would. Scoped to this
-     * run's agent (cache key = conversation + agent) so parallel agents in one
-     * conversation never cross-pollinate. An empty projection is cached too (the
-     * negative-cache case that spares tool-free conversations the queries every turn).
+     * run's agent and branch (cache key = conversation + agent + branch) so parallel
+     * agents in one conversation, and sibling branches, never cross-pollinate. An empty
+     * projection is cached too (the negative-cache case that spares tool-free
+     * conversations the queries every turn). The run's reply row is stored with the entry,
+     * so the entry is no longer served once a rerun of its turn replaces that row.
      * Same-node edge semantics (failed step INSERTs, concurrent completions) are
      * documented on the cache class. Called from {@link finalizeAgentRun}.
      * @private
@@ -2305,6 +2538,16 @@ export declare class BaseAgent {
      * not here.
      */
     private static readonly carryForwardPredicate;
+    /**
+     * The row predicate for the stopped-run carry-forward's step query: the completed, successful
+     * Actions and Tool steps of the run the user stopped. Declared beside
+     * {@link carryForwardPredicate} for the same reason it is: one place to change what counts.
+     */
+    private static readonly stoppedRunCarryForwardPredicate;
+    /** An action parameter's direction, as the action executor stamps it. */
+    private static readonly actionOutputParamType;
+    /** A stopped-run result section is never cut below this many characters, whatever the budget. */
+    private static readonly minStoppedRunSectionChars;
     /**
      * Display name of the seeded system prompt behind summarizeRange's recursive
      * sub-call (see metadata/prompts/.summarize-range-prompt.json). Resolved with a
@@ -2890,12 +3133,22 @@ export declare class BaseAgent {
     private finalizePayloadCheckStep;
     /** Adds the payload change check's message to the conversation, for the agent's next turn. */
     private injectPayloadCheckMessage;
+    /**
+     * The {@link AIPromptExecutionScope} of model work this run starts outside the agent's own turn —
+     * summarizing a range, compacting a message or the conversation, decision calls (FinishIf,
+     * discovery, catalog narrowing, decision requests, the payload change check) and self-check
+     * rubrics. Each built its params with only `contextUser`, so it ran on the platform's keys and
+     * default configuration inside a run on a customer's keys, and under a `'RuntimeOnly'` scope
+     * would have bypassed it.
+     */
+    private runPromptExecutionScope;
     /**
      * 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.
+     * Under a `'RuntimeOnly'` credential scope a refusal leaves the action with no key for that class.
      */
     protected actionMayUseRuntimeAPIKey(action: MJActionEntityExtended, driverClass: string, params: ExecuteAgentParams): boolean;
     /**
@@ -3066,6 +3319,19 @@ export declare class BaseAgent {
      * @private
      */
     private formatActionParameter;
+    /**
+     * The `user`-role record of what the model asked to run on an Actions turn ("[You invoked ...]").
+     * Shared by the live Actions step and the stopped-run resume, so a resumed turn reads exactly
+     * like one the loop wrote. See the Actions step for why it is a user-role annotation.
+     * @protected
+     */
+    protected buildActionInvocationMessage(actions: AgentAction[]): string;
+    /**
+     * The action-results message body: a header naming any failures, then each result in the
+     * compact markdown shape. Shared by the live Actions step and the stopped-run resume.
+     * @protected
+     */
+    protected buildActionResultsMessage(actionSummaries: ActionResultSummary[]): string;
     /**
      * Formats an array of action result summaries as compact markdown instead of
      * pretty-printed JSON.  This typically saves 60-70 % of the tokens that the
@@ -3217,6 +3483,12 @@ export declare class BaseAgent {
      * @private
      */
     private getActionCategoryName;
+    /**
+     * Throws unless `lastRunId` is absent or a UUID. The value can come from a client, and the run
+     * initialization places it in `ExtraFilter` clauses (the payload lookup, {@link validateRunChain}
+     * and {@link resolvePlanModeGate}).
+     */
+    private assertLastRunIdIsUUID;
     /**
      * Initializes the agent run tracking by creating MJAIAgentRunEntityExtended and setting up context.
      *
@@ -3511,8 +3783,10 @@ export declare class BaseAgent {
      * by one in-flight sub-agent would race the others' reads.
      *
      * Uses `structuredClone` (Node 17+) where available; falls back to a JSON
-     * round-trip for environments without it. Returns the original value on
-     * non-cloneable inputs.
+     * round-trip (`ToPlainJSON`) for environments without it AND when
+     * `structuredClone` throws (a Proxy such as a live JSONType `<Field>Object`
+     * view, or functions). Returns the original value — with an error logged —
+     * only when even the JSON clone fails.
      *
      * **JSON fallback caveats** — the round-trip is *not* shape-preserving:
      *   - `Date` → ISO string
@@ -3739,10 +4013,6 @@ export declare class BaseAgent {
      * (or timeout), then adds results to the conversation and continues.
      */
     private executeClientToolsStep;
-    /**
-     * Format client tool results as a compact markdown summary for the conversation.
-     */
-    private formatClientToolResultsAsMarkdown;
     /**
      * Executes a 'Skill' next step: activates one or more skills the LLM requested by name.
      * Activating a skill (1) appends its full `Instructions` to the conversation so they take
@@ -4054,12 +4324,10 @@ export declare class BaseAgent {
     /**
      * Resolves the file storage account ID for this agent's file artifacts.
      *
-     * Resolution chain (first non-null wins):
-     * 1. Runtime override (`params.override?.storageAccountId`)
-     * 2. Agent-level (`params.agent.DefaultStorageAccountID`)
-     * 3. Category hierarchy — walks up the agent's category tree via `ParentID`
-     * 4. Agent Type-level (`agentType.DefaultStorageAccountID`)
-     * 5. System fallback — single active storage account, if only one exists
+     * Delegates to {@link AIEngineBase.ResolveAgentStorageAccountID}, the shared golden path:
+     * runtime override (`params.override?.storageAccountId`) → agent → category tree → agent type →
+     * system fallback (the single active account, or the most recently updated one with a
+     * once-per-agent warning when several are active).
      *
      * This method is `protected` so subclasses can override the resolution logic
      * for custom storage routing (e.g., routing by file type or tenant).
@@ -4238,6 +4506,22 @@ export declare class BaseAgent {
      * @returns {Promise<ExecuteAgentResult>} The cancelled result
      */
     private createCancelledResult;
+    /**
+     * Maps the reason an abort signal carried to the run's `CancellationReason` value: the
+     * watchdog's stop relay raises {@link AgentRunWatchdog.UserCancelAbortReason} for a row marked
+     * `User Request`; the wall-clock guard's reason starts with {@link AgentTimeoutAbortReason};
+     * anything else (an upstream caller's token, a shutdown) is `System`.
+     */
+    static CancellationReasonForAbort(reason: string | null | undefined): NonNullable<MJAIAgentRunEntityExtended['CancellationReason']>;
+    /**
+     * The payload recorded at the end of the latest step that recorded one, as its serialized
+     * string, or null when no step has. Steps are examined from the highest `StepNumber` down
+     * (array order is spawn order, which a sub-step can interleave).
+     */
+    static LastStepPayload(steps: ReadonlyArray<{
+        StepNumber: number;
+        PayloadAtEnd: string | null;
+    }> | null | undefined): string | null;
     /**
      * Finalizes the agent run with success.
      *