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

package/dist/base-agent.js

@@ -10,12 +10,12 @@
  * @author MemberJunction.com
  * @since 2.49.0
  */
-import { FileStorageEngineBase, MJEnvironmentEntityExtended } from '@memberjunction/core-entities';
+import { MJEnvironmentEntityExtended, ConversationEngine } from '@memberjunction/core-entities';
 import { BuildActionToolSet, FilterDeclarableActions, SanitizeToolName } from './native-tools/action-tool-builder.js';
 import { BuildNativeToolSet, COMPLETE_TASK_TOOL, 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 { MJAIAgentRunEntityExtended, ResolvePromptRunUserID } from "@memberjunction/ai-core-plus";
 import { Metadata, RunView, LogStatus, LogStatusEx, LogError, LogErrorEx, IsVerboseLoggingEnabled, DatabaseProviderBase, ToPlainJSON } from '@memberjunction/core';
 import { AgentRunWatchdog } from './agent-run-watchdog.js';
 import { AIPromptRunner, GetToolCallingDecision } from '@memberjunction/ai-prompts';
@@ -23,7 +23,7 @@ import { BaseRealtimeModel, GetAIAPIKey, CredentialScopeAllows, MakeAIAPIKeyReso
 import { BaseAgentType } from './agent-types/base-agent-type.js';
 import { ProviderRubricEngine } from '@memberjunction/rubrics';
 import { ExecuteSelfCheck, PickSelfCheckLink } from './self-check.js';
-import { CopyScalarsAndArrays, JSONValidator, MJGlobal, NormalizeUUID, SafeExpressionEvaluator, UUIDsEqual, EscapeSQLString, IsPlainObject, CleanAndParseJSON } from '@memberjunction/global';
+import { CopyScalarsAndArrays, JSONValidator, MJGlobal, NormalizeUUID, SafeExpressionEvaluator, UUIDsEqual, EscapeSQLString, IsPlainObject, CleanAndParseJSON, IsValidUUID } 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
@@ -31,7 +31,9 @@ import { CrushCode } from '@memberjunction/context-crush/code';
 import { RealtimeSessionRunner } from './realtime/realtime-session-runner.js';
 import { ResolveNarrationInstructionsTemplate } from './realtime/realtime-narration.js';
 import { BuildRealtimeOverridesJson, BuildVoiceMannerSection, GetNarrationPaceMs, GetProviderVoiceSettings, GetSessionTuningSettings, GetModelCatalogSessionSettings, DeepMergeConfigs, ResolveEffectiveRealtimeConfig } from './realtime/realtime-coagent-config.js';
-import { SelectRealtimeVendorForModel } from './realtime/realtime-vendor-resolution.js';
+import { ListRealtimeVendorsForModel, SelectRealtimeVendorForModel } from './realtime/realtime-vendor-resolution.js';
+import { ChooseRealtimeVendorForAvatar, RealtimeModelShowsAvatar } from './realtime/realtime-video-output-gate.js';
+import { RealtimeSessionCanShowAvatar } from './realtime/realtime-avatar-resolution.js';
 import { RealtimeClientSessionService, WarnOnUnmatchedProviderVoice } from './realtime/realtime-client-session-service.js';
 import { BuildRealtimeAgentFraming } from './realtime/realtime-tool-broker.js';
 import { ReadHostTools, ReadTrimmedString } from './realtime/bridge-host-params.js';
@@ -71,6 +73,7 @@ import { PipelineExecutor, PipelineToolRegistry, ActionInvocable, ArtifactToolIn
 import { GetValueFromPath, SetMappedValue } from '@memberjunction/ai-core-plus';
 import { AgentDataPreloader } from './AgentDataPreloader.js';
 import { ClientToolRequestManager } from './ClientToolRequestManager.js';
+import { BuildClientToolResultMessage, ResolveClientToolResultMaxChars, ReplaceMediaBlocksWithStubs, IsMediaBlock, IMAGE_BLOCK_TOKEN_ESTIMATE } from './client-tool-results.js';
 import { ConversationMessageResolver } from './utils/ConversationMessageResolver.js';
 import _ from 'lodash';
 /**
@@ -210,6 +213,13 @@ export class BaseAgent {
          */
         this._generalValidationRetryCount = 0;
         this._agentRun = null;
+        /**
+         * 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.
+         */
+        this._runAbortController = null;
         /**
          * The task graph this run submitted and is now waiting on, or null.
          *
@@ -317,6 +327,11 @@ export class BaseAgent {
          * Armed only when the run has a conversationId (the cross-turn context gate).
          */
         this._conversationToolManager = new 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.
+         */
+        this._conversationBranches = [];
         /**
          * Manages in-flight durable memory writes for the current agent run.
          * Only consulted when the agent has AllowMemoryWrite enabled.
@@ -823,6 +838,12 @@ export class BaseAgent {
      * on the right one, and neither shows up as an error.
      */
     static { this.DEFAULT_ABSOLUTE_MAX_ITERATIONS = 5000; }
+    /**
+     * 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 { this.AgentTimeoutAbortReason = 'Agent execution exceeded maxExecutionTimeMs'; }
     /**
      * The resolved FileStorageAccount ID for this agent run. Set during Execute()
      * via the hierarchical resolution chain (Runtime → Agent → Category → Type → fallback).
@@ -1481,13 +1502,15 @@ export class BaseAgent {
         }
         const timeoutId = setTimeout(() => {
             if (!timeoutController.signal.aborted) {
-                timeoutController.abort(`Agent '${params.agent.Name}' exceeded maxExecutionTimeMs (${agentTimeoutMS}ms)`);
+                timeoutController.abort(`${BaseAgent.AgentTimeoutAbortReason}: agent '${params.agent.Name}' ran past ${agentTimeoutMS}ms`);
             }
         }, agentTimeoutMS);
         // Route the merged signal back through `params` so the existing body of
         // Execute (and downstream sub-agent invocations that propagate
         // `cancellationToken`) observe it.
         params.cancellationToken = timeoutController.signal;
+        // Hold it for the watchdog's stop relay (registered once the run row exists).
+        this._runAbortController = timeoutController;
         try {
             this.logStatus(`🤖 Starting execution of agent '${params.agent.Name}'`, true, params);
             // =====================================================================================
@@ -1546,7 +1569,11 @@ export class BaseAgent {
             // 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).
             // 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);
+            // On a branch, the tools page only rows on that branch's path.
+            this._conversationBranches = wrappedParams.conversationId && wrappedParams.ConversationBranchID
+                ? await ConversationEngine.LoadBranchesFresh(wrappedParams.conversationId, params.contextUser, this.ProviderToUse)
+                : [];
+            this._conversationToolManager.Initialize(wrappedParams.conversationId || null, params.contextUser, wrappedParams.ConversationHistoryFrom ?? null, wrappedParams.ConversationBranchID ?? null, this._conversationBranches);
             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 —
@@ -1675,7 +1702,11 @@ export class BaseAgent {
                     primaryScopeEntityId = primaryEntity.ID;
                 }
             }
-            const [config] = await Promise.all([
+            // The user's new message, captured by identity before anything below adds to the list, so a
+            // resumed stopped run can be spliced in ahead of it once the parallel phase settles.
+            const continuationMessage = wrappedParams.conversationMessages[wrappedParams.conversationMessages.length - 1];
+            // Positions matter: [0] is the config and [5] the stopped-run continuation.
+            const [config, , , , , stoppedRunContinuation] = await Promise.all([
                 this.loadAgentConfiguration(params.agent),
                 this.preloadAgentData(wrappedParams),
                 this.InjectContextMemory(typeof inputText === 'string' ? inputText : '', params.agent, userId, companyId, params.contextUser, wrappedParams.conversationMessages, primaryScopeEntityId, primaryScopeRecordId, secondaryScopes, scopeConfig),
@@ -1684,10 +1715,15 @@ export class BaseAgent {
                 // conversationId). Runs here so the results are in the messages before
                 // the pre-turn compaction check and the first prompt.
                 this.injectPriorTurnToolResults(wrappedParams),
+                // If the previous turn was STOPPED by the user, load what it did so this turn continues
+                // the work instead of redoing it. Applied below, after this phase settles.
+                this.loadStoppedRunContinuation(wrappedParams),
                 // Decision discovery (plan Task 3.1), off unless the decisionsEnabled and decisionDiscovery prompt
                 // params are true: may add a <suggested_agent> system message, within DECISION_DISCOVERY_TIMEOUT_MS.
                 this.InjectDecisionDiscovery(params.agent, params.contextUser, wrappedParams.conversationMessages, params.data)
             ]);
+            // Resume (or summarize) a run the user stopped, now that nothing else is writing the list.
+            this.applyStoppedRunContinuation(wrappedParams, stoppedRunContinuation, continuationMessage);
             // Inject scope-resolved prompt parts (role-faithful) for this agent's prompt, alongside
             // memory/RAG. Synchronous — parts are cached on AIEngine. Uses the same run scope.
             this.InjectScopedPromptParts(params.agent, wrappedParams.conversationMessages, primaryScopeEntityId, primaryScopeRecordId, secondaryScopes);
@@ -1775,6 +1811,7 @@ export class BaseAgent {
             // consumers that re-read `params` after the call see what they
             // passed in, not our chained signal.
             params.cancellationToken = upstreamToken;
+            this._runAbortController = null;
             // A cancellation, or an error thrown out of the step loop, leaves any held decision
             // requests unasked. The terminate path has already logged and cleared its own.
             this.skipHeldDecisions(params, this.runEndForHeldDecisions());
@@ -1954,10 +1991,16 @@ export class BaseAgent {
             ? (params.data?.realtimeSelfNames).filter((n) => typeof n === 'string')
             : undefined;
         const hostTools = ReadHostTools(params.data?.realtimeHostTools);
+        // Note: resolveHostTools is an in-process callback function passed directly in params.data.
+        // It will not survive process boundaries or cross-host job queue serialization.
+        const resolveHostTools = typeof params.data?.resolveHostTools === 'function'
+            ? params.data.resolveHostTools
+            : undefined;
         return {
             CoAgent: params.agent,
             TargetAgentID: targetID,
             HostTools: hostTools,
+            ResolveHostTools: resolveHostTools,
             HostFraming: ReadTrimmedString(params.data?.realtimeHostFraming, 'realtimeHostFraming'),
             PriorTranscript: ReadTrimmedString(params.data?.realtimePriorTranscript, 'realtimePriorTranscript'),
             ConversationID: ReadTrimmedString(params.data?.conversationId, 'conversationId'),
@@ -1974,6 +2017,12 @@ export class BaseAgent {
             UserID: params.contextUser?.ID,
             DisableAutoResponse: meetingMode || undefined,
             SelfNames: selfNames,
+            // The bridge's bot can publish the agent's avatar into the room (set by the room coordinator after it asked).
+            AvatarDelivery: params.data?.realtimeAvatarDelivery === 'room' ? 'room' : undefined,
+            // A server-side session: without room delivery it can't show an avatar, so the model choice prefers none.
+            ServerSide: true,
+            // A phone call (set by the telephony hosts): the caller sees no video, so the session asks for no avatar.
+            PhoneCall: params.data?.realtimePhoneCall === true || undefined,
             // App awareness (Move 1/3/4): the app the session runs in (sources the app cascade layer +
             // RelevantAgents → allowed-agent union) and the live app-context snapshot injected at mint.
             // Both ride params.data, the same conduit async agents use for appContext.
@@ -1989,7 +2038,8 @@ export 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
@@ -2013,31 +2063,62 @@ export class BaseAgent {
         // brings its own credential for a vendor we hold no platform key for now reaches that
         // vendor — which is the point of bringing your own key, not a side effect of it.
         const resolveAPIKey = MakeAIAPIKeyResolver(params.apiKeys, undefined, params.CredentialScope);
+        // The vendor follows whether the run will show an avatar, by the co-agent session prep's rule: a vendor that
+        // renders avatars (Vertex AI for Gemini 3.8 Live) only when it will, or when it is the only keyed vendor.
+        const showsAvatar = this.realtimeRunShowsAvatar(params);
         const candidates = this.selectRealtimeModelCandidates(params.agent, overrideModelID);
         for (const model of candidates) {
             const vendor = SelectRealtimeVendorForModel(model.ID, resolveAPIKey);
-            if (!vendor) {
-                continue;
-            }
-            const apiKey = resolveAPIKey(vendor.DriverClass);
-            if (!apiKey) {
-                continue;
-            }
-            const instance = MJGlobal.Instance.ClassFactory.CreateInstance(BaseRealtimeModel, vendor.DriverClass, apiKey);
-            if (!instance) {
+            const first = vendor ? this.instantiateRealtimeRunVendor(model.ID, vendor, resolveAPIKey) : null;
+            if (!vendor || !first) {
                 continue;
             }
-            return {
-                model: instance,
-                modelID: model.ID,
-                vendorID: vendor.VendorID,
-                modelVendorID: vendor.ModelVendorID,
-                apiName: vendor.APIName,
-                driverClass: vendor.DriverClass
-            };
+            return ChooseRealtimeVendorForAvatar(vendor, first, ListRealtimeVendorsForModel(model.ID), showsAvatar, {
+                Instantiate: (other) => this.instantiateRealtimeRunVendor(model.ID, other, resolveAPIKey),
+                RendersAvatar: (resolution) => RealtimeModelShowsAvatar({ ModelID: resolution.modelID, APIName: resolution.apiName, Model: resolution.model }, AIEngine.Instance),
+            });
         }
         return 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.
+     */
+    realtimeRunShowsAvatar(params) {
+        if (this.resolveRealtimeEffectiveConfig(params.agent).realtime?.video?.enabled !== true) {
+            return false;
+        }
+        return RealtimeSessionCanShowAvatar({
+            ServerSide: true,
+            AvatarDelivery: params.data?.realtimeAvatarDelivery === 'room' ? 'room' : undefined,
+            PhoneCall: params.data?.realtimePhoneCall === true,
+        });
+    }
+    /**
+     * 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.
+     */
+    instantiateRealtimeRunVendor(modelID, vendor, resolveAPIKey) {
+        const apiKey = resolveAPIKey(vendor.DriverClass);
+        if (!apiKey) {
+            return null;
+        }
+        const instance = MJGlobal.Instance.ClassFactory.CreateInstance(BaseRealtimeModel, vendor.DriverClass, apiKey);
+        if (!instance) {
+            return null;
+        }
+        return {
+            model: instance,
+            modelID,
+            vendorID: vendor.VendorID,
+            modelVendorID: vendor.ModelVendorID,
+            apiName: vendor.APIName,
+            driverClass: vendor.DriverClass
+        };
+    }
     /**
      * 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
@@ -5600,23 +5681,15 @@ export 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
      * @protected
      */
     contentToString(content) {
-        if (typeof content === 'string') {
-            return content;
-        }
-        // Content is an array of blocks - convert to string
-        return content.map((block) => {
-            if (block.type === 'text') {
-                return block.content;
-            }
-            return `[${block.type}: ${block.content}]`;
-        }).join('\n');
+        return ReplaceMediaBlocksWithStubs(content);
     }
     /**
      * Smart trimming of message content based on detected format.
@@ -5888,9 +5961,7 @@ export class BaseAgent {
                 break;
             const originalTokens = candidate.tokens;
             const originalMessage = candidate.message;
-            const originalContent = typeof originalMessage.content === 'string'
-                ? originalMessage.content
-                : JSON.stringify(originalMessage.content);
+            const originalContent = ReplaceMediaBlocksWithStubs(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));
@@ -5964,9 +6035,7 @@ export class BaseAgent {
                 break;
             const originalTokens = candidate.tokens;
             const originalMessage = candidate.message;
-            const originalContent = typeof originalMessage.content === 'string'
-                ? originalMessage.content
-                : JSON.stringify(originalMessage.content);
+            const originalContent = ReplaceMediaBlocksWithStubs(originalMessage.content);
             // Aggressive compaction - keep only first 200 chars
             const compactedContent = await this.compactMessage(originalMessage, {
                 compactMode: 'First N Chars',
@@ -6256,20 +6325,7 @@ The context is now within limits. Please retry your request with the recovered c
             if (!body) {
                 return;
             }
-            const message = {
-                role: 'user',
-                content: body,
-                metadata: {
-                    turnAdded: 0,
-                    messageType: BaseAgent.toolResultMessageType,
-                    expirationTurns: 2,
-                    expirationMode: 'Compact',
-                    compactMode: 'First N Chars',
-                    compactLength: 500,
-                    compactPromptId: '',
-                },
-            };
-            params.conversationMessages.push(message);
+            params.conversationMessages.push(this.buildCarryForwardMessage(body));
             this.logStatus(`[PriorTurnToolResults] Carried ${steps.length} tool result(s) forward from the previous run`, true, params);
         }
         catch (error) {
@@ -6277,6 +6333,504 @@ The context is now within limits. Please retry your request with the recovered c
             this.logStatus(`[PriorTurnToolResults] Skipped (contained error): ${error instanceof Error ? error.message : error}`, true, params);
         }
     }
+    /**
+     * 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
+     */
+    async injectStoppedRunResults(params) {
+        const continuationMessage = params.conversationMessages[params.conversationMessages.length - 1];
+        const continuation = await this.loadStoppedRunContinuation(params);
+        this.applyStoppedRunContinuation(params, continuation, continuationMessage);
+    }
+    /**
+     * 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
+     */
+    async loadStoppedRunContinuation(params) {
+        if (!params.conversationId || this._depth !== 0 || params.ConversationHistoryFrom) {
+            return null;
+        }
+        try {
+            // A caller that chained this run (the run resolver, after its own stopped-predecessor
+            // lookup, or a client continuing a run) already named the predecessor: check that one
+            // row rather than searching the conversation again. Only an unchained run searches.
+            const runId = params.lastRunId
+                ? await this.userStoppedRunIdIfStopped(params.lastRunId, params)
+                : await this.findUserStoppedPredecessorRunId(params);
+            if (!runId) {
+                return null;
+            }
+            const mode = params.stopContinuationMode ?? BaseAgent.DefaultStopContinuationMode;
+            const steps = mode === 'full_stack'
+                ? await this.loadStoppedRunStack(runId, params)
+                : await this.loadStoppedRunResultSteps(runId, params);
+            return { RunID: runId, Mode: mode, Steps: steps };
+        }
+        catch (error) {
+            this.logStatus(`[StoppedRunResults] Skipped (contained error): ${error instanceof Error ? error.message : error}`, true, params);
+            return 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
+     */
+    applyStoppedRunContinuation(params, continuation, continuationMessage) {
+        if (!continuation) {
+            return;
+        }
+        try {
+            if (continuation.Mode === 'full_stack' && this.tryResumeStoppedRunStack(params, continuation, continuationMessage)) {
+                return;
+            }
+            const steps = continuation.Steps.filter(BaseAgent.isCarriedForwardResultStep);
+            const body = BaseAgent.BuildStoppedRunResultsMessage(steps, BaseAgent.maxStoppedRunResultChars);
+            if (!body) {
+                return;
+            }
+            params.conversationMessages.push(this.buildCarryForwardMessage(body));
+            this.logStatus(`[StoppedRunResults] Carried ${steps.length} completed step result(s) forward from stopped run ${continuation.RunID}`, true, params);
+        }
+        catch (error) {
+            this.logStatus(`[StoppedRunResults] Skipped (contained error): ${error instanceof Error ? error.message : error}`, true, params);
+        }
+    }
+    /**
+     * 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
+     */
+    tryResumeStoppedRunStack(params, continuation, continuationMessage) {
+        try {
+            const resumed = this.buildResumedStoppedRunTurns(continuation.Steps, params);
+            if (resumed && BaseAgent.SpliceResumedTurns(params.conversationMessages, resumed, continuationMessage)) {
+                this.logStatus(`[StoppedRunResume] Resumed ${resumed.length} message(s) from stopped run ${continuation.RunID}`, true, params);
+                return true;
+            }
+            this.logStatus(`[StoppedRunResume] Stack of stopped run ${continuation.RunID} could not be resumed; carrying its results as a summary`, true, params);
+        }
+        catch (error) {
+            this.logStatus(`[StoppedRunResume] Resume failed (${error instanceof Error ? error.message : error}); carrying its results as a summary`, true, params);
+        }
+        return false;
+    }
+    /** The mode a run uses when the caller does not set {@link ExecuteAgentParams.stopContinuationMode}. */
+    static { this.DefaultStopContinuationMode = 'full_stack'; }
+    /**
+     * 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 { this.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. */
+    static { this.stoppedBeforeRunResultCode = 'NOT_EXECUTED'; }
+    static { this.stoppedBeforeRunMessage = 'Not executed: the user stopped the run before this action finished.'; }
+    /**
+     * 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
+     */
+    buildResumedStoppedRunTurns(steps, params) {
+        const prompts = steps.filter(s => s.StepType === 'Prompt');
+        if (prompts.length === 0) {
+            return null;
+        }
+        const lastPrompt = prompts[prompts.length - 1];
+        const loopTurns = BaseAgent.ExtractStoppedRunLoopTurns(BaseAgent.readPromptStepStack(prompts[0]), BaseAgent.readPromptStepStack(lastPrompt));
+        if (!loopTurns) {
+            return null;
+        }
+        const decision = lastPrompt.Status === 'Completed' ? BaseAgent.readPromptStepDecision(lastPrompt) : null;
+        const tail = this.buildStoppedRunTail(decision, steps.filter(s => s.StepNumber > lastPrompt.StepNumber), params);
+        return [...loopTurns, ...tail].map(BaseAgent.restampResumedTurn);
+    }
+    /**
+     * 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, lastStack) {
+        if (!firstStack?.length || !lastStack?.length) {
+            return null;
+        }
+        const key = (m) => `${m.role}\u0000${JSON.stringify(m.content)}`;
+        const startKey = key(firstStack[firstStack.length - 1]);
+        const expectedAt = firstStack.length - 1;
+        const at = lastStack[expectedAt] && key(lastStack[expectedAt]) === startKey
+            ? expectedAt
+            : lastStack.map(key).lastIndexOf(startKey);
+        if (at < 0) {
+            return null;
+        }
+        return lastStack.slice(at + 1).filter(m => m.metadata?.volatileState !== true);
+    }
+    /**
+     * 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, resumed, continuationMessage) {
+        const at = continuationMessage ? messages.indexOf(continuationMessage) : -1;
+        if (at < 0 || continuationMessage?.role !== 'user') {
+            return false;
+        }
+        const notice = { role: 'user', content: BaseAgent.StoppedRunResumeNotice };
+        const previous = messages[at - 1];
+        const stoppedReplyAt = previous?.role === 'assistant' && !previous.toolCalls?.length ? at - 1 : at;
+        messages.splice(at, 0, notice);
+        messages.splice(stoppedReplyAt, 0, ...resumed);
+        return true;
+    }
+    /**
+     * 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
+     */
+    buildStoppedRunTail(decision, tailSteps, params) {
+        const tail = [];
+        if (!decision) {
+            return tail;
+        }
+        const scratch = { ...params, conversationMessages: tail };
+        const native = decision.nativeTurn?.sendResultsNatively === true;
+        if (native && decision.nativeTurn) {
+            tail.push(BuildAssistantToolCallTurn(decision.nativeTurn));
+        }
+        if (decision.step === 'Actions' && decision.actions?.length) {
+            if (!native) {
+                tail.push({ role: 'user', content: this.buildActionInvocationMessage(decision.actions) });
+            }
+            const summaries = this.summarizeStoppedRunActions(decision.actions, tailSteps);
+            this.appendActionResults(scratch, summaries, this.buildActionResultsMessage(summaries), undefined, decision);
+        }
+        else {
+            const results = BaseAgent.BuildStoppedRunResultsMessage(tailSteps.filter(BaseAgent.isCarriedForwardResultStep), BaseAgent.maxStoppedRunResultChars);
+            if (results) {
+                tail.push(this.buildCarryForwardMessage(results));
+            }
+        }
+        this.reconcileUnansweredToolCalls(scratch);
+        return tail;
+    }
+    /** One result per requested action, in request order: its completed step's result, or not executed. @private */
+    summarizeStoppedRunActions(requested, tailSteps) {
+        const completed = tailSteps.filter(s => s.StepType === 'Actions' && s.Status === 'Completed');
+        const used = new Set();
+        return requested.map(action => {
+            const step = completed.find(s => !used.has(s) && BaseAgent.readStoppedActionName(s) === action.name);
+            const summary = step ? this.summarizeStoppedActionStep(action.name, step) : null;
+            if (!step || !summary) {
+                return {
+                    actionName: action.name,
+                    success: false,
+                    params: [],
+                    resultCode: BaseAgent.stoppedBeforeRunResultCode,
+                    message: BaseAgent.stoppedBeforeRunMessage,
+                };
+            }
+            used.add(step);
+            return summary;
+        });
+    }
+    /**
+     * 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
+     */
+    summarizeStoppedActionStep(actionName, step) {
+        let output;
+        try {
+            output = step.OutputData ? JSON.parse(step.OutputData) : {};
+        }
+        catch {
+            return null;
+        }
+        const result = output.actionResult;
+        if (!result) {
+            return null;
+        }
+        const success = result.success === true;
+        const outputParams = (result.parameters ?? []).filter(p => p.Type === 'Both' || p.Type === 'Output');
+        const actionEntity = ActionEngineServer.Instance.Actions?.find(a => a.Name === actionName);
+        return {
+            actionName,
+            success,
+            params: this.interceptLargeBinaryContent(outputParams, actionEntity),
+            resultCode: result.resultCode || (success ? 'SUCCESS' : 'ERROR'),
+            message: result.message || (success ? 'Action completed' : 'Unknown error'),
+        };
+    }
+    /** The message stack a prompt step recorded as its input, or null. @private */
+    static readPromptStepStack(step) {
+        try {
+            const input = step.InputData ? JSON.parse(step.InputData) : {};
+            return Array.isArray(input.conversationMessages) ? input.conversationMessages : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /** The decision a completed prompt step recorded, or null. @private */
+    static readPromptStepDecision(step) {
+        try {
+            const output = step.OutputData ? JSON.parse(step.OutputData) : {};
+            return output.nextStep ?? null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /** The action an Actions step ran, from its recorded input, or null. @private */
+    static readStoppedActionName(step) {
+        try {
+            const input = step.InputData ? JSON.parse(step.InputData) : {};
+            return input.actionName ?? null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * 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
+     */
+    static restampResumedTurn(message) {
+        return message.metadata?.turnAdded !== undefined
+            ? { ...message, metadata: { ...message.metadata, turnAdded: 0 } }
+            : message;
+    }
+    /** A step whose result the summary carries: a completed, successful Actions or Tool step. @private */
+    static isCarriedForwardResultStep(step) {
+        const types = BaseAgent.stoppedRunCarryForwardPredicate.stepTypes;
+        return types.includes(step.StepType) &&
+            step.Status === BaseAgent.stoppedRunCarryForwardPredicate.stepStatus &&
+            step.Success === true;
+    }
+    /**
+     * 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
+     */
+    buildCarryForwardMessage(content) {
+        return {
+            role: 'user',
+            content,
+            metadata: {
+                turnAdded: 0,
+                messageType: BaseAgent.toolResultMessageType,
+                expirationTurns: 2,
+                expirationMode: 'Compact',
+                compactMode: 'First N Chars',
+                compactLength: 500,
+                compactPromptId: '',
+            },
+        };
+    }
+    /**
+     * 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
+     */
+    async findUserStoppedPredecessorRunId(params) {
+        const rv = RunView.FromMetadataProvider(this.ProviderToUse);
+        const newest = await rv.RunView({
+            EntityName: 'MJ: AI Agent Runs',
+            ExtraFilter: MJAIAgentRunEntityExtended.BuildStoppedPredecessorFilter(params.conversationId, params.agent.ID, params.ConversationBranchID ?? null, this._conversationBranches),
+            OrderBy: '__mj_CreatedAt DESC',
+            MaxRows: 1,
+            Fields: ['ID', 'Status', 'CancellationReason'],
+            ResultType: 'simple',
+            // The row this looks for was written by the Stop button moments ago; read the database, not a cache.
+            BypassCache: true,
+        }, params.contextUser);
+        const run = newest.Success ? newest.Results?.[0] : undefined;
+        return run && MJAIAgentRunEntityExtended.IsUserStopped(run.Status, run.CancellationReason) ? run.ID : null;
+    }
+    /**
+     * `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
+     */
+    async userStoppedRunIdIfStopped(runId, params) {
+        if (!IsValidUUID(runId)) {
+            return null;
+        }
+        const rv = RunView.FromMetadataProvider(this.ProviderToUse);
+        const result = await rv.RunView({
+            EntityName: 'MJ: AI Agent Runs',
+            ExtraFilter: `ID='${runId}'`,
+            MaxRows: 1,
+            Fields: ['ID', 'Status', 'CancellationReason'],
+            ResultType: 'simple',
+            // The row this checks was written by the Stop button moments ago; read the database, not a cache.
+            BypassCache: true,
+        }, params.contextUser);
+        const run = result.Success ? result.Results?.[0] : undefined;
+        return run && MJAIAgentRunEntityExtended.IsUserStopped(run.Status, run.CancellationReason) ? run.ID : null;
+    }
+    /**
+     * 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
+     */
+    async loadStoppedRunStack(runId, params) {
+        const rv = RunView.FromMetadataProvider(this.ProviderToUse);
+        const steps = await rv.RunView({
+            EntityName: 'MJ: AI Agent Run Steps',
+            ExtraFilter: `AgentRunID='${runId}'`,
+            OrderBy: 'StepNumber ASC',
+            Fields: ['StepNumber', 'StepType', 'StepName', 'Status', 'Success', 'InputData', 'OutputData'],
+            ResultType: 'simple',
+            BypassCache: true,
+        }, params.contextUser);
+        return steps.Success ? (steps.Results || []) : [];
+    }
+    /** The completed, successful Actions and Tool steps of a stopped run, in step order. @private */
+    async loadStoppedRunResultSteps(runId, params) {
+        const rv = RunView.FromMetadataProvider(this.ProviderToUse);
+        const steps = await rv.RunView({
+            EntityName: 'MJ: AI Agent Run Steps',
+            ExtraFilter: `AgentRunID='${runId}' AND StepType IN (${BaseAgent.stoppedRunCarryForwardPredicate.stepTypes.map(t => `'${t}'`).join(', ')}) ` +
+                `AND Status='${BaseAgent.stoppedRunCarryForwardPredicate.stepStatus}' AND Success=1`,
+            OrderBy: 'StepNumber ASC',
+            Fields: ['StepNumber', 'StepType', 'StepName', 'Status', 'Success', 'InputData', 'OutputData'],
+            ResultType: 'simple',
+            BypassCache: true,
+        }, params.contextUser);
+        return steps.Success ? (steps.Results || []) : [];
+    }
+    /**
+     * 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.
+     */
+    static { this.maxStoppedRunResultChars = 28_000; }
+    /**
+     * 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, maxChars) {
+        const sections = [];
+        const perSectionMax = Math.max(BaseAgent.minStoppedRunSectionChars, Math.floor(maxChars / Math.max(steps.length, 1)));
+        let usedChars = 0;
+        let dropped = 0;
+        for (const step of steps) {
+            const section = BaseAgent.renderStoppedRunStep(step);
+            if (!section) {
+                continue;
+            }
+            const capped = section.length > perSectionMax
+                ? `${section.slice(0, perSectionMax)}\n[truncated]`
+                : section;
+            if (usedChars + capped.length > maxChars && sections.length > 0) {
+                dropped++;
+                continue;
+            }
+            usedChars += capped.length;
+            sections.push(capped);
+        }
+        if (sections.length === 0) {
+            return null;
+        }
+        const header = 'Your previous turn was stopped by the user before it finished. The actions and tools listed below ' +
+            'were ALREADY EXECUTED in that turn and their results are still valid. Treat each entry as a result you already ' +
+            'have: do not run the action or call a tool again for it, and do not invoke the action names below as tools. ' +
+            'Continue from where the stopped turn left off rather than starting over.';
+        const droppedNote = dropped > 0 ? `\n\n[${dropped} additional result(s) omitted for size; re-call those if needed]` : '';
+        return `${header}\n${sections.join('\n\n')}${droppedNote}`;
+    }
+    /** One stopped-run step as a result section, or null when it carries nothing reusable. @private */
+    static renderStoppedRunStep(step) {
+        if (step.StepType === 'Tool') {
+            return BaseAgent.BuildPriorTurnToolResultsMessage([{ OutputData: step.OutputData }], Number.MAX_SAFE_INTEGER)
+                ?.split('\n').slice(1).join('\n') || null; // the sibling renderer's body without its header line
+        }
+        if (step.StepType !== 'Actions' || !step.InputData || !step.OutputData) {
+            return null;
+        }
+        let input;
+        let output;
+        try {
+            input = JSON.parse(step.InputData);
+            output = JSON.parse(step.OutputData);
+        }
+        catch {
+            return null;
+        }
+        const result = output.actionResult;
+        if (!input.actionName || result?.success !== true) {
+            return null;
+        }
+        const outputs = {};
+        for (const param of result.parameters ?? []) {
+            if (param.Type === BaseAgent.actionOutputParamType && param.Value !== undefined && param.Value !== null) {
+                outputs[param.Name] = param.Value;
+            }
+        }
+        const body = Object.keys(outputs).length > 0 ? RenderToolResultData(outputs) : (result.message ?? '');
+        if (!body) {
+            return null;
+        }
+        // Deliberately NOT the inline-tool heading (`### tool({...})`): an agent shown that shape for an
+        // action tried to call the action as a conversation tool. Say what it is in words.
+        return `### Already executed: action "${input.actionName}" with params ${JSON.stringify(input.actionParams ?? {})}\n` +
+            `Result:\n\`\`\`json\n${body}\n\`\`\``;
+    }
+    /**
+     * 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, agentId, branchId, branches, statusList) {
+        return `ConversationID='${conversationId}' AND Status IN (${statusList}) AND ParentRunID IS NULL AND AgentID='${agentId}'`
+            + ` AND ${MJAIAgentRunEntityExtended.BuildReplyOnBranchPathFilter(conversationId, branchId, branches)}`;
+    }
     /**
      * Loads this agent's previous settled root run's Tool steps for this conversation
      * (settled = {@link settledRunStatuses}: Completed or AwaitingFeedback).
@@ -6292,7 +6846,8 @@ The context is now within limits. Please retry your request with the recovered c
      * @private
      */
     async loadPriorTurnToolResultSteps(params) {
-        const cached = PriorTurnToolResultCache.Instance.Get(params.conversationId, params.agent.ID);
+        const branchId = params.ConversationBranchID ?? null;
+        const cached = PriorTurnToolResultCache.Instance.Get(params.conversationId, params.agent.ID, branchId);
         if (cached) {
             this.logStatus(`[PriorTurnToolResults] Prior-run tool results served from cache (${cached.length} step(s), no DB lookup)`, true, params);
             return cached;
@@ -6301,10 +6856,11 @@ The context is now within limits. Please retry your request with the recovered c
         const statusList = predicate.runStatuses.map(s => `'${s}'`).join(', ');
         const rv = RunView.FromMetadataProvider(this.ProviderToUse);
         // AgentID scopes provenance: in a multi-agent conversation, agent B must never
-        // inherit agent A's results labeled "your previous turn".
+        // inherit agent A's results labeled "your previous turn". The branch path scopes it
+        // the same way: a run on a sibling branch is never carried forward.
         const priorRun = await rv.RunView({
             EntityName: 'MJ: AI Agent Runs',
-            ExtraFilter: `ConversationID='${params.conversationId}' AND Status IN (${statusList}) AND ParentRunID IS NULL AND AgentID='${params.agent.ID}'`,
+            ExtraFilter: BaseAgent.BuildPriorTurnRunFilter(params.conversationId, params.agent.ID, branchId, this._conversationBranches, statusList),
             OrderBy: '__mj_CreatedAt DESC',
             MaxRows: 1,
             Fields: ['ID'],
@@ -6330,9 +6886,11 @@ The context is now within limits. Please retry your request with the recovered c
      * 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
@@ -6347,7 +6905,7 @@ The context is now within limits. Please retry your request with the recovered c
         const records = (this._agentRun.Steps || [])
             .filter(s => s.StepType === predicate.stepType && s.Status === predicate.stepStatus)
             .map(s => ({ OutputData: s.OutputData || null }));
-        PriorTurnToolResultCache.Instance.Set(conversationId, this._agentRun.AgentID, records);
+        PriorTurnToolResultCache.Instance.Set(conversationId, this._agentRun.AgentID, this._executeParams?.ConversationBranchID ?? null, records, this._agentRun.ConversationDetailID ?? null);
     }
     /**
      * Tool families whose step results are eligible for prior-turn carry-forward —
@@ -6373,7 +6931,7 @@ The context is now within limits. Please retry your request with the recovered c
      * ({@link carryForwardPredicate} → DB filter + cache-population gate) and the
      * post-turn compaction gate ({@link startPostTurnCompaction}).
      */
-    static { this.settledRunStatuses = ['Completed', 'AwaitingFeedback']; }
+    static { this.settledRunStatuses = MJAIAgentRunEntityExtended.SettledStatuses; }
     /**
      * The carry-forward row predicate — the SINGLE source shared by the two places that
      * must select the same rows or the cache diverges from the DB path: the RunView
@@ -6391,6 +6949,19 @@ The context is now within limits. Please retry your request with the recovered c
         stepStatus: 'Completed',
         runStatuses: BaseAgent.settledRunStatuses,
     }; }
+    /**
+     * 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.
+     */
+    static { this.stoppedRunCarryForwardPredicate = {
+        stepTypes: ['Actions', 'Tool'],
+        stepStatus: 'Completed',
+    }; }
+    /** An action parameter's direction, as the action executor stamps it. */
+    static { this.actionOutputParamType = 'Output'; }
+    /** A stopped-run result section is never cut below this many characters, whatever the budget. */
+    static { this.minStoppedRunSectionChars = 1_500; }
     /**
      * Display name of the seeded system prompt behind summarizeRange's recursive
      * sub-call (see metadata/prompts/.summarize-range-prompt.json). Resolved with a
@@ -7788,13 +8359,16 @@ The context is now within limits. Please retry your request with the recovered c
      */
     buildAgentBaseCatalog(agent, engine) {
         // Resolve sub-agents: direct ParentID children + active relationships, de-duped, ordered.
+        // Only Active agents are kept, so a Disabled relationship target never reaches the catalog.
         const activeSubAgents = engine.Agents.filter(a => UUIDsEqual(a.ParentID, agent.ID) && a.Status === 'Active')
             .sort((a, b) => a.ExecutionOrder - b.ExecutionOrder);
         const activeAgentRelationships = engine.AgentRelationships.filter(ar => UUIDsEqual(ar.AgentID, agent.ID) && ar.Status === 'Active');
         const uniqueActiveSubAgentIDs = new Set();
         activeSubAgents.forEach(a => uniqueActiveSubAgentIDs.add(a.ID));
         activeAgentRelationships.forEach(ar => uniqueActiveSubAgentIDs.add(ar.SubAgentID));
-        const uniqueActiveSubAgents = Array.from(uniqueActiveSubAgentIDs).map(id => engine.Agents.find(a => UUIDsEqual(a.ID, id)));
+        const uniqueActiveSubAgents = Array.from(uniqueActiveSubAgentIDs)
+            .map(id => engine.Agents.find(a => UUIDsEqual(a.ID, id)))
+            .filter((a) => !!a && a.Status === 'Active');
         // Resolve actions from the agent's active AIAgentAction junctions.
         const agentActions = engine.AgentActions.filter(aa => UUIDsEqual(aa.AgentID, agent.ID) && aa.Status === 'Active');
         const baseActionsRaw = ActionEngineServer.Instance.Actions.filter(a => agentActions.some(aa => UUIDsEqual(aa.ActionID, a.ID)));
@@ -8968,7 +9542,7 @@ The context is now within limits. Please retry your request with the recovered c
         lines.push('records. When you choose client tools, set nextStep.type to "ClientTools".');
         lines.push('');
         lines.push('NOTE: Do NOT use client tools for asking the user questions or collecting input.');
-        lines.push('Use the "Chat" step for that. Client tools are for programmatic UI interaction only.');
+        lines.push('Use the "Chat" step for that. Client tools read and change the user\'s UI; some return an image.');
         lines.push('');
         for (const tool of tools) {
             const categoryTag = tool.Category ? ` [${tool.Category}]` : '';
@@ -9061,6 +9635,44 @@ The context is now within limits. Please retry your request with the recovered c
         const desc = param.Description ? ` — ${param.Description}` : '';
         return `\`${param.Name}\`${requiredMarker}${suffix}${desc}${defaultStr}`;
     }
+    /**
+     * 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
+     */
+    buildActionInvocationMessage(actions) {
+        if (actions.length === 1) {
+            const aa = actions[0];
+            if (!aa.params || Object.keys(aa.params).length === 0) {
+                return `[You invoked the **${aa.name}** action.]`;
+            }
+            const paramsList = Object.entries(aa.params)
+                .map(([key, value]) => `• **${key}**: ${this.formatParamValueForMessage(value)}`)
+                .join('\n');
+            return `[You invoked the **${aa.name}** action with parameters:\n${paramsList}\n]`;
+        }
+        return `[You invoked **${actions.length} actions** in parallel:\n\n` + actions.map((aa, index) => {
+            const actionText = `${index + 1}. **${aa.name}**`;
+            if (!aa.params || Object.keys(aa.params).length === 0) {
+                return actionText;
+            }
+            const paramsList = Object.entries(aa.params)
+                .map(([key, value]) => `   • **${key}**: ${this.formatParamValueForMessage(value)}`)
+                .join('\n');
+            return `${actionText}\n${paramsList}`;
+        }).join('\n\n') + '\n]';
+    }
+    /**
+     * 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
+     */
+    buildActionResultsMessage(actionSummaries) {
+        const failed = actionSummaries.filter(a => !a.success).length;
+        const header = failed > 0 ? `${failed} of ${actionSummaries.length} action(s) failed:` : 'Action results:';
+        return `${header}\n${this.formatActionResultsAsMarkdown(actionSummaries)}`;
+    }
     /**
      * 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
@@ -9430,6 +10042,16 @@ The context is now within limits. Please retry your request with the recovered c
         // For now, returning a placeholder
         return 'General';
     }
+    /**
+     * 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}).
+     */
+    assertLastRunIdIsUUID(lastRunId) {
+        if (lastRunId && !IsValidUUID(lastRunId)) {
+            throw new Error('Invalid lastRunId: expected the UUID of a prior AI Agent Run.');
+        }
+    }
     /**
      * Initializes the agent run tracking by creating MJAIAgentRunEntityExtended and setting up context.
      *
@@ -9437,6 +10059,7 @@ The context is now within limits. Please retry your request with the recovered c
      * @param {ExecuteAgentParams} params - The execution parameters
      */
     async initializeAgentRun(params) {
+        this.assertLastRunIdIsUUID(params.lastRunId);
         // Handle autoPopulateLastRunPayload if requested
         let modifiedParams = params;
         if (params.lastRunId && params.autoPopulateLastRunPayload) {
@@ -9445,7 +10068,9 @@ The context is now within limits. Please retry your request with the recovered c
             const lastRunResult = await rv.RunView({
                 EntityName: 'MJ: AI Agent Runs',
                 ExtraFilter: `ID='${params.lastRunId}'`,
-                ResultType: 'simple' // Avoid recursive loading
+                ResultType: 'simple', // Avoid recursive loading
+                // A stopped predecessor wrote its FinalPayload moments ago; read the database, not a cache.
+                BypassCache: true
             }, params.contextUser);
             if (lastRunResult.Success && lastRunResult.Results.length > 0) {
                 const lastRun = lastRunResult.Results[0];
@@ -9606,7 +10231,7 @@ The context is now within limits. Please retry your request with the recovered c
         // server-side DB provider can heartbeat via SQL; client/non-DB providers simply opt out.
         const runProvider = params.provider || this._activeProvider;
         if (runProvider instanceof DatabaseProviderBase && params.contextUser) {
-            AgentRunWatchdog.Instance.Track(this._agentRun.ID, runProvider, params.contextUser);
+            AgentRunWatchdog.Instance.Track(this._agentRun.ID, runProvider, params.contextUser, this._runAbortController ?? undefined);
         }
         // Invoke callback if provided
         if (modifiedParams.onAgentRunCreated) {
@@ -12123,40 +12748,7 @@ The context is now within limits. Please retry your request with the recovered c
             // which (pre-guardrail) looped forever. Phrasing it in second person under the `user`
             // role keeps the memory while removing the false assistant-prose exemplar. The
             // human-facing narration is emitted separately via onProgress above.
-            let actionMessage;
-            if (actions.length === 1) {
-                const aa = actions[0];
-                actionMessage = `[You invoked the **${aa.name}** action`;
-                // Add parameters if they exist
-                if (aa.params && Object.keys(aa.params).length > 0) {
-                    const paramsList = Object.entries(aa.params)
-                        .map(([key, value]) => {
-                        const displayValue = this.formatParamValueForMessage(value);
-                        return `• **${key}**: ${displayValue}`;
-                    })
-                        .join('\n');
-                    actionMessage += ` with parameters:\n${paramsList}\n]`;
-                }
-                else {
-                    actionMessage += '.]';
-                }
-            }
-            else {
-                actionMessage = `[You invoked **${actions.length} actions** in parallel:\n\n` + actions.map((aa, index) => {
-                    let actionText = `${index + 1}. **${aa.name}**`;
-                    // Add parameters if they exist
-                    if (aa.params && Object.keys(aa.params).length > 0) {
-                        const paramsList = Object.entries(aa.params)
-                            .map(([key, value]) => {
-                            const displayValue = this.formatParamValueForMessage(value);
-                            return `   • **${key}**: ${displayValue}`;
-                        })
-                            .join('\n');
-                        actionText += `\n${paramsList}`;
-                    }
-                    return actionText;
-                }).join('\n\n') + '\n]';
-            }
+            const actionMessage = this.buildActionInvocationMessage(actions);
             if (addConversationMessage) {
                 // Record as a `user`-role environment annotation (no metadata - permanent record).
                 // See the note above on why this is NOT an `assistant` turn.
@@ -12275,10 +12867,7 @@ The context is now within limits. Please retry your request with the recovered c
             // Check if any actions failed
             const failedActions = actionSummaries.filter(a => !a.success);
             // Add user message with the results — compact markdown instead of JSON
-            const header = failedActions.length > 0
-                ? `${failedActions.length} of ${actionSummaries.length} action(s) failed:`
-                : `Action results:`;
-            const resultsMessage = `${header}\n${this.formatActionResultsAsMarkdown(actionSummaries)}`;
+            const resultsMessage = this.buildActionResultsMessage(actionSummaries);
             // Build metadata from AI Agent Actions configuration
             // If multiple actions, use the most restrictive (shortest) expiration settings
             let metadata;
@@ -12480,24 +13069,20 @@ The context is now within limits. Please retry your request with the recovered c
             });
             const timeoutMs = tool.TimeoutMs ?? defaultTimeout;
             const response = await ClientToolRequestManager.Instance.RequestClientTool(`ct_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`, tool.Name, tool.Params, params.sessionID, agentRunID, timeoutMs, tool.Description);
-            await this.finalizeStepEntity(stepEntity, response.Success, response.ErrorMessage, { result: response.Result });
+            await this.finalizeStepEntity(stepEntity, response.Success, response.ErrorMessage, {
+                result: response.Result,
+                media: response.Media?.map(m => ({ mimeType: m.MimeType, bytes: Math.floor((m.Base64.length * 3) / 4), width: m.Width, height: m.Height }))
+            });
             results.push({
                 ToolName: tool.Name,
                 Success: response.Success,
                 Result: response.Result,
+                Media: response.Media,
                 ErrorMessage: response.ErrorMessage
             });
         }
         // Format results as conversation message
-        const resultsMarkdown = this.formatClientToolResultsAsMarkdown(results);
-        params.conversationMessages.push({
-            role: 'user',
-            content: resultsMarkdown,
-            metadata: {
-                turnAdded: this._promptTurnCount,
-                messageType: 'client-tool-result'
-            }
-        });
+        params.conversationMessages.push(BuildClientToolResultMessage(results, this._promptTurnCount, ResolveClientToolResultMaxChars(this._agentTypePromptParams)));
         // If the LLM already declared taskComplete=true alongside the client tools,
         // honor that intent now that tools have executed — no need for another LLM call.
         if (previousDecision.terminateAfterExecution) {
@@ -12518,29 +13103,6 @@ The context is now within limits. Please retry your request with the recovered c
         }
         return await this.executePromptStep(params, config, previousDecision, stepCount);
     }
-    /**
-     * Format client tool results as a compact markdown summary for the conversation.
-     */
-    formatClientToolResultsAsMarkdown(results) {
-        const failedCount = results.filter(r => !r.Success).length;
-        const header = failedCount > 0
-            ? `${failedCount} of ${results.length} client tool(s) failed:`
-            : 'Client tool results:';
-        const lines = results.map(r => {
-            const icon = r.Success ? '✓' : '✗';
-            let line = `${icon} **${r.ToolName}**: ${r.Success ? 'succeeded' : 'failed'}`;
-            if (r.ErrorMessage)
-                line += ` — ${r.ErrorMessage}`;
-            if (r.Success && r.Result != null) {
-                const resultStr = typeof r.Result === 'string' ? r.Result : JSON.stringify(r.Result);
-                if (resultStr.length <= 500) {
-                    line += `\n  Result: ${resultStr}`;
-                }
-            }
-            return line;
-        });
-        return `${header}\n${lines.join('\n')}`;
-    }
     /**
      * 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
@@ -13447,12 +14009,10 @@ The context is now within limits. Please retry your request with the recovered c
     /**
      * 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).
@@ -13461,68 +14021,7 @@ The context is now within limits. Please retry your request with the recovered c
      * @returns The resolved FileStorageAccount ID, or null if none configured
      */
     async getStorageAccountID(params) {
-        // 1. Runtime override — highest priority
-        if (params.override?.storageAccountId) {
-            return params.override.storageAccountId;
-        }
-        // 2. Agent-level override
-        if (params.agent.DefaultStorageAccountID) {
-            return params.agent.DefaultStorageAccountID;
-        }
-        // 3. Category tree walk
-        const categoryId = params.agent.CategoryID;
-        if (categoryId) {
-            try {
-                const categories = AIEngine.Instance.AgentCategories;
-                let currentId = categoryId;
-                const visited = new Set();
-                while (currentId && !visited.has(currentId)) {
-                    visited.add(currentId);
-                    const cat = categories.find(c => UUIDsEqual(c.ID, currentId));
-                    if (!cat)
-                        break;
-                    if (cat.DefaultStorageAccountID)
-                        return cat.DefaultStorageAccountID;
-                    currentId = cat.ParentID;
-                }
-            }
-            catch (error) {
-                LogError(`Error resolving category storage account: ${error.message}`);
-            }
-        }
-        // 4. Agent Type-level default
-        const agentTypeId = params.agent.TypeID;
-        if (agentTypeId) {
-            const agentType = AIEngine.Instance.AgentTypes.find(at => UUIDsEqual(at.ID, agentTypeId));
-            if (agentType?.DefaultStorageAccountID) {
-                return agentType.DefaultStorageAccountID;
-            }
-        }
-        // 5. System fallback — use cached metadata (already loaded during engine Config)
-        const activeAccounts = FileStorageEngineBase.Instance.AccountsWithProviders
-            .filter(a => a.provider.IsActive);
-        if (activeAccounts.length === 0) {
-            // No storage configured — return null, inline base64 fallback handles it downstream
-            return null;
-        }
-        if (activeAccounts.length === 1) {
-            return activeAccounts[0].account.ID;
-        }
-        // 2+ active accounts but nothing configured at any level
-        const agentName = params.agent.Name || params.agent.ID;
-        const typeName = params.agent.TypeID
-            ? AIEngine.Instance.AgentTypes.find(at => UUIDsEqual(at.ID, params.agent.TypeID))?.Name || params.agent.TypeID
-            : 'unknown';
-        const categoryName = params.agent.CategoryID
-            ? AIEngine.Instance.AgentCategories.find(c => UUIDsEqual(c.ID, params.agent.CategoryID))?.Name || params.agent.CategoryID
-            : 'none';
-        const accountNames = activeAccounts.map(a => `'${a.account.Name}' (${a.provider.Name})`).join(', ');
-        throw new Error(`Multiple active file storage accounts detected (${accountNames}) but no DefaultStorageAccountID is configured ` +
-            `for agent '${agentName}', category '${categoryName}', or agent type '${typeName}'.\n` +
-            `To fix: Set DefaultStorageAccountID on one of the following (in order of priority):\n` +
-            `  1. Agent '${agentName}' — for this specific agent\n` +
-            `  2. Agent Category '${categoryName}' — for all agents in this category\n` +
-            `  3. Agent Type '${typeName}' — for all agents of this type`);
+        return AIEngine.Instance.ResolveAgentStorageAccountID(params.agent, params.override?.storageAccountId);
     }
     /**
      * Resolves the target user ID from a resolved assignment strategy.
@@ -14315,15 +14814,59 @@ The context is now within limits. Please retry your request with the recovered c
             this._agentRun.CompletedAt = new Date();
             this._agentRun.Success = false;
             this._agentRun.ErrorMessage = message;
+            // Save() writes every column, so an in-memory null here would overwrite the reason the
+            // Stop button wrote on the row. Record the reason the abort signal carried instead. The
+            // signal is consulted first because most call sites pass a fixed message naming WHERE
+            // the run was cancelled ('during prompt execution'), not WHY.
+            const signalReason = this._runAbortController?.signal.reason;
+            this._agentRun.CancellationReason = BaseAgent.CancellationReasonForAbort(typeof signalReason === 'string' ? signalReason : message);
+            // A stop is not supposed to lose the work. The run row only learns its FinalPayload on a
+            // normal finish, but every completed step already recorded the payload as it stood, so
+            // the last of those is what the next turn (chained by LastRunID) starts from.
+            if (!this._agentRun.FinalPayload) {
+                const lastPayload = BaseAgent.LastStepPayload(this._agentRun.Steps);
+                if (lastPayload) {
+                    this._agentRun.FinalPayload = lastPayload;
+                }
+            }
             // Calculate total tokens even for cancelled runs
             this.applyTokenStatsToRun(this._agentRun, this.calculateTokenStats());
             await this._agentRun.Save();
+            AgentRunWatchdog.Instance.Untrack(this._agentRun.ID);
         }
         return {
             success: false,
             agentRun: this._agentRun
         };
     }
+    /**
+     * 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) {
+        if (reason === AgentRunWatchdog.UserCancelAbortReason) {
+            return 'User Request';
+        }
+        if (reason && reason.startsWith(BaseAgent.AgentTimeoutAbortReason)) {
+            return 'Timeout';
+        }
+        return 'System';
+    }
+    /**
+     * 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) {
+        if (!steps || steps.length === 0) {
+            return null;
+        }
+        const ordered = [...steps].sort((a, b) => (b.StepNumber ?? 0) - (a.StepNumber ?? 0));
+        const withPayload = ordered.find(s => typeof s.PayloadAtEnd === 'string' && s.PayloadAtEnd.length > 0);
+        return withPayload?.PayloadAtEnd ?? null;
+    }
     /**
      * Finalizes the agent run with success.
      *
@@ -14840,6 +15383,7 @@ The context is now within limits. Please retry your request with the recovered c
         }
         const outcome = await ConversationCompactionManager.CompactIfNeeded({
             ConversationId: params.conversationId,
+            BranchID: params.ConversationBranchID ?? null,
             Agent: params.agent,
             AgentType: config?.agentType || null,
             Budget: budget,
@@ -15040,9 +15584,7 @@ The context is now within limits. Please retry your request with the recovered c
      * @protected
      */
     async compactMessage(message, metadata, params) {
-        const originalContent = typeof message.content === 'string'
-            ? message.content
-            : JSON.stringify(message.content);
+        const originalContent = ReplaceMediaBlocksWithStubs(message.content);
         switch (metadata.compactMode) {
             case 'First N Chars': {
                 const length = metadata.compactLength;
@@ -15153,12 +15695,15 @@ The context is now within limits. Please retry your request with the recovered c
             || messageType === 'loop-result';
     }
     estimateTokens(content, modelName) {
-        const text = typeof content === 'string'
-            ? content
-            : JSON.stringify(content);
-        // Use heuristic token estimation (fast, good enough for context management)
-        // Avoids heavy tokenizer dependencies while providing ~10-20% accuracy
-        return this.heuristicTokenCount(text);
+        if (typeof content === 'string') {
+            return this.heuristicTokenCount(content);
+        }
+        // Each media block counts as IMAGE_BLOCK_TOKEN_ESTIMATE, not by its base64 length.
+        let tokens = 0;
+        for (const block of content) {
+            tokens += IsMediaBlock(block) ? IMAGE_BLOCK_TOKEN_ESTIMATE : this.heuristicTokenCount(block.content);
+        }
+        return tokens;
     }
     /**
      * Provides an improved heuristic token count when tokenizer is unavailable.