@memberjunction/ai-agents 5.40.2 → 5.42.0

package/dist/base-agent.js

@@ -14,19 +14,24 @@ import { FileStorageEngineBase } from '@memberjunction/core-entities';
 import { Metadata, RunView, LogStatus, LogStatusEx, LogError, LogErrorEx, IsVerboseLoggingEnabled, DatabaseProviderBase } from '@memberjunction/core';
 import { AgentRunWatchdog } from './agent-run-watchdog.js';
 import { AIPromptRunner } from '@memberjunction/ai-prompts';
+import { BaseRealtimeModel, GetAIAPIKey } from '@memberjunction/ai';
 import { BaseAgentType } from './agent-types/base-agent-type.js';
-import { CopyScalarsAndArrays, JSONValidator, SafeExpressionEvaluator, UUIDsEqual } from '@memberjunction/global';
+import { CopyScalarsAndArrays, JSONValidator, MJGlobal, SafeExpressionEvaluator, UUIDsEqual } from '@memberjunction/global';
+import { RealtimeSessionRunner } from './realtime/realtime-session-runner.js';
+import { ResolveNarrationInstructionsTemplate } from './realtime/realtime-narration.js';
+import { BuildRealtimeOverridesJson, BuildVoiceMannerSection, GetNarrationPaceMs, GetProviderVoiceSettings, ResolveEffectiveRealtimeConfig } from './realtime/realtime-coagent-config.js';
+import { RealtimeClientSessionService } from './realtime/realtime-client-session-service.js';
+import { BuildRealtimeAgentFraming } from './realtime/realtime-tool-broker.js';
 import { AIEngine } from '@memberjunction/aiengine';
 import { ActionEngineServer } from '@memberjunction/actions';
 import { AIAgentPermissionHelper } from '@memberjunction/ai-engine-base';
-import { AgentContextInjector } from './agent-context-injector.js';
-import { AgentPreExecutionRAG } from './agent-pre-execution-rag.js';
-import { RerankerService } from '@memberjunction/ai-reranker';
-import { AIPromptParams, ChildPromptParam, ConversationUtility, ParseFileOutputRef, parseAssignmentStrategy } from '@memberjunction/ai-core-plus';
+import { AgentMemoryContextBuilder } from './agent-memory-context-builder.js';
+import { AIPromptParams, ChildPromptParam, ConversationUtility, ParseFileOutputRef, parseAssignmentStrategy, initAgentRunStep, finalizeAgentRunStep, AgentRunStepSaveQueue } from '@memberjunction/ai-core-plus';
 import { AgentRunner } from './AgentRunner.js';
 import { PayloadManager } from './PayloadManager.js';
 import { ScratchpadManager } from './ScratchpadManager.js';
 import { ArtifactToolManager } from './ArtifactToolManager.js';
+import { MemoryWriteManager } from './MemoryWriteManager.js';
 import { PipelineExecutor, PipelineToolRegistry, ActionInvocable, ArtifactToolInvocable, BuildPipelineToolDocs, formatFinalOutput, summarizePipelineStages, } from './pipeline/index.js';
 import { AgentDataPreloader } from './AgentDataPreloader.js';
 import { ClientToolRequestManager } from './ClientToolRequestManager.js';
@@ -89,20 +94,13 @@ export class BaseAgent {
          */
         this._promptRunner = new AIPromptRunner();
         /**
-         * List of pending database save Promises for observability step records.
-         * Awaited concurrently in finalizeAgentRun() to prevent blocking.
+         * Fire-and-forget save orchestration for this run's observability step records: the create INSERT is
+         * fired without blocking the agent flow (the PK is client-generated by `NewRecord()`), each finalize
+         * UPDATE chains after its step's INSERT and force-persists (`IgnoreDirtyState`), and all pending saves
+         * are flushed (`allSettled`) in {@link finalizeAgentRun}. The pattern lives once in
+         * {@link AgentRunStepSaveQueue} (shared with `@memberjunction/computer-use-engine`'s step tracker).
          */
-        this._pendingSaves = [];
-        /**
-         * Queue map to chain database saves sequentially per step entity.
-         * Prevents UPDATE queries running before INSERT queries on quick steps.
-         *
-         * Keyed by the step ENTITY INSTANCE, not its `ID`: a new step's `ID` is empty at create time and
-         * only gets populated during its INSERT `Save()`, so keying by `ID` would file the create and the
-         * finalize under different buckets and defeat the chain — letting the UPDATE race ahead of the
-         * INSERT on millisecond-fast steps (e.g. pipelines), which left them stuck at `Running`.
-         */
-        this._stepSavePromises = new Map();
+        this._stepSaveQueue = new AgentRunStepSaveQueue();
         /**
          * Active per-request metadata provider, set at the start of Execute().
          * Defaults to the global Metadata.Provider; overridden when a per-request
@@ -209,6 +207,11 @@ export class BaseAgent {
          * Allows agents to explore input artifacts on demand.
          */
         this._artifactToolManager = new ArtifactToolManager();
+        /**
+         * Manages in-flight durable memory writes for the current agent run.
+         * Only consulted when the agent has AllowMemoryWrite enabled.
+         */
+        this._memoryWriteManager = new MemoryWriteManager();
         /**
          * Effective actions available to this agent after applying actionChanges.
          * Populated during gatherPromptTemplateData() and used for validation in executeActionsStep().
@@ -253,21 +256,16 @@ export class BaseAgent {
          * @private
          */
         this.MAX_RECOVERY_ATTEMPTS = 1;
-        /**
-         * Storage for injected memory context to prepend to prompts
-         */
-        this._memoryContext = '';
         /**
          * Storage for injected notes and examples to include in result
          */
         this._injectedMemory = { notes: [], examples: [] };
         /**
          * Storage for injected pre-execution RAG context (Phase 1C of search-scopes-rag-plus).
-         * Contains the formatted `<retrieved_context>` system-message block actually injected
-         * into `conversationMessages`, plus the structured per-scope / combined result detail
-         * for downstream observability and artifact persistence.
+         * Contains the structured per-scope / combined result detail for downstream observability
+         * and artifact persistence. The formatted `<retrieved_context>` system-message block is
+         * unshifted onto `conversationMessages` by the shared {@link AgentMemoryContextBuilder}.
          */
-        this._ragContext = '';
         this._injectedRAG = null;
         /**
          * Determines the request type ID based on the Chat step's context.
@@ -1006,6 +1004,7 @@ export class BaseAgent {
             // Reset scratchpad and artifact tools for each new execution (ephemeral per run)
             this._scratchpadManager.Clear();
             this._artifactToolManager.Clear();
+            this._memoryWriteManager.Clear();
             // Initialize artifact tools with any input artifacts attached to the run.
             // Artifacts arrive as a typed first-class field on ExecuteAgentParams —
             // they are NOT routed through `data` because prompt-template rendering
@@ -1146,6 +1145,21 @@ export class BaseAgent {
             // Must wait for config from Phase 2 because it needs the resolved agent type and
             // prompt configuration to initialize the type-specific state machine.
             await this.initializeAgentType(wrappedParams, config);
+            // =====================================================================================
+            // SESSION-DRIVEN BRANCH (Realtime agent type)
+            //
+            // For session-driven agent types (the Realtime / Realtime Co-Agent type, marked by
+            // `IsSessionDriven === true`), we do NOT enter the iterative reasoning loop. Instead we
+            // hand control to a RealtimeSessionRunner that drives a long-lived duplex model session.
+            //
+            // This is the ONLY entry point into the realtime path. Loop and Flow agent types do not
+            // expose `IsSessionDriven`, so `isSessionDrivenAgentType(...)` returns false for them and
+            // their execution falls through to `executeAgentInternal` below — byte-for-byte unchanged.
+            // =====================================================================================
+            if (this.isSessionDrivenAgentType(this.AgentTypeInstance)) {
+                this.logStatus(`🎙️ Agent '${params.agent.Name}' is session-driven — routing to RealtimeSessionRunner`, true, params);
+                return await this.executeRealtimeSession(wrappedParams, config);
+            }
             // Execute the agent's internal logic with wrapped parameters
             this.logStatus(`🚀 Executing agent '${params.agent.Name}' internal logic`, true, params);
             const executionResult = await this.executeAgentInternal(wrappedParams, config);
@@ -1201,6 +1215,676 @@ export class BaseAgent {
             params.cancellationToken = upstreamToken;
         }
     }
+    // =====================================================================================
+    // REALTIME (SESSION-DRIVEN) AGENT SUPPORT
+    //
+    // The methods below back the session-driven branch taken in Execute() for the Realtime
+    // agent type. They are entered ONLY via that guarded branch; Loop/Flow agents never reach
+    // them. The bulk of the work is building a RealtimeSessionRunnerDeps from BaseAgent's real
+    // collaborators (model resolution, sub-agent delegation, tool execution, transcript
+    // persistence, and usage checkpointing) and then driving RealtimeSessionRunner.Run().
+    // =====================================================================================
+    /**
+     * Type guard for whether the resolved agent-type instance is session-driven.
+     *
+     * Detects the Realtime agent type without importing it (and without `instanceof`, which is
+     * brittle under bundler class-duplication) by duck-typing the `IsSessionDriven` getter that
+     * `RealtimeAgentType` adds. `BaseAgentType` (and Loop/Flow) do not expose this member, so the
+     * guard returns `false` for them and the iterative loop runs unchanged.
+     *
+     * @param agentType The resolved agent-type instance for this run.
+     * @returns `true` only when the type explicitly marks itself session-driven.
+     */
+    isSessionDrivenAgentType(agentType) {
+        return agentType.IsSessionDriven === true;
+    }
+    /**
+     * Drives a session-driven (Realtime) agent run end-to-end.
+     *
+     * Resolves the realtime model, assembles the session parameters (system prompt + memory/context),
+     * builds the {@link RealtimeSessionRunnerDeps} from this agent's collaborators, runs the
+     * {@link RealtimeSessionRunner}, and maps the result onto the finalized `AIAgentRun`.
+     *
+     * If no realtime model can be resolved (expected today, before the P3 drivers / P4 model
+     * metadata land), it finalizes the run as a clean FAILED result with an actionable message
+     * rather than throwing — a mis-provisioned environment must not crash the caller.
+     *
+     * @template R The caller's expected payload type (unused on the realtime path; the session
+     *   produces transcript/usage rather than a structured payload).
+     * @param params The wrapped execution parameters.
+     * @param config The loaded agent configuration (provides the system prompt, if any).
+     * @returns The finalized {@link ExecuteAgentResult}.
+     */
+    async executeRealtimeSession(params, config) {
+        // 1) Resolve the realtime model (overridable seam — tests inject a mock).
+        const modelResolution = await this.resolveRealtimeModel(params);
+        if (!modelResolution) {
+            const message = `Agent '${params.agent.Name}' is session-driven (Realtime) but no usable Realtime model could be ` +
+                `resolved. Configure a model of AIModelType 'Realtime' with an active vendor DriverClass and a ` +
+                `valid API key (e.g. AI_VENDOR_API_KEY__<driver>). This is expected until the realtime drivers ` +
+                `and model metadata are provisioned.`;
+            this.logError(message, { agent: params.agent, category: 'RealtimeSession' });
+            return await this.createFailureResult(message, params.contextUser);
+        }
+        // 2) Create the single long-lived AIPromptRun that usage is checkpointed onto.
+        const promptRun = await this.createRealtimePromptRun(params, config, modelResolution);
+        // 3) Build the injected deps and run the session.
+        try {
+            const deps = await this.buildRealtimeSessionDeps(params, config, modelResolution, promptRun);
+            const runner = new RealtimeSessionRunner(deps);
+            const sessionResult = await runner.Run();
+            return await this.finalizeRealtimeRun(params, sessionResult);
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            this.logError(`Realtime session failed for agent '${params.agent.Name}': ${msg}`, {
+                agent: params.agent,
+                category: 'RealtimeSession'
+            });
+            return await this.createFailureResult(msg, params.contextUser);
+        }
+    }
+    /**
+     * Opens a **raw** {@link IRealtimeSession} for this agent — the duplex model connection a Realtime
+     * Bridge hands to `AIBridgeEngine.StartBridgeSession` so the agent can talk + hear over a media
+     * transport (a LiveKit room, a Zoom/Teams meeting, a phone call). The bridge engine owns turn-taking
+     * and the transport seam, so this deliberately returns the **session itself**, NOT a
+     * {@link RealtimeSessionRunner} (which is the client-direct topology's own orchestration loop).
+     *
+     * It reuses the EXACT same resolution + assembly as {@link executeRealtimeSession} — model selection
+     * ({@link resolveRealtimeModel}), agent configuration ({@link loadAgentConfiguration}), effective-config
+     * persona/voice ({@link resolveRealtimeEffectiveConfig}), and the system-prompt + memory context
+     * ({@link buildRealtimeSessionParams}) — then opens the session via
+     * {@link BaseRealtimeModel.StartSession}. Tools are intentionally NOT pre-populated: the
+     * `invoke-target-agent` + interactive-surface tools are a runner concern; a bridge that needs them
+     * registers them on the returned session itself.
+     *
+     * @param params The execution parameters (agent + context user + the request-scoped provider). A fresh
+     *   bridge session typically passes an empty `conversationMessages` array.
+     * @returns The live realtime session.
+     * @throws When the agent configuration fails to load or no usable Realtime model can be resolved.
+     */
+    async StartBridgeRealtimeSession(params) {
+        // Mirror Execute()'s provider wiring so the realtime helpers operate on the request-scoped provider.
+        this._activeProvider = params.provider ?? Metadata.Provider;
+        const provider = params.provider ?? Metadata.Provider;
+        // A LiveKit / Zoom / Teams bridge is a thin TRANSPORT over the realtime co-agent — it does NOT build
+        // session prep itself. It CONSUMES the one shared producer
+        // ({@link RealtimeClientSessionService.PrepareRealtimeSessionParams}) so the agent's identity (it
+        // speaks first-person AS the target — Sage / Marketing Agent / …), the model + voice precedence
+        // cascade, the tool set (always incl. invoke-target-agent), and memory are byte-for-byte identical to
+        // the native realtime chat. Bridges differ ONLY in opening the session server-side (StartSession) and
+        // their media transport. See plans/realtime/realtime-core-host-convergence.md.
+        // ONE service instance: it produces the prep AND wires the long-lived runtime, so the in-flight
+        // delegation registry (barge-in cancel) is shared between them.
+        const service = new RealtimeClientSessionService();
+        const input = this.buildBridgePrepInput(params);
+        const contextUser = params.contextUser;
+        const prep = await service.PrepareRealtimeSessionParams(input, contextUser, provider);
+        if (!prep.Success || !prep.Resolution || !prep.SessionParams) {
+            throw new Error(prep.ErrorMessage ?? `Failed to prepare a realtime session for agent '${params.agent.Name}'. ` +
+                `Configure an Active AIModelType 'Realtime' model with an active vendor whose DriverClass has a ` +
+                `resolvable API key.`);
+        }
+        const session = await prep.Resolution.Model.StartSession(prep.SessionParams);
+        // Phase 2: wire the SAME core runtime the native chat uses — real `invoke-target-agent` delegation
+        // (target runs via AgentRunner, nested + tracked) + co-agent run/prompt-run observability, finalized
+        // when the bridge calls `session.Close()`. No host-local tool re-implementation. The runtime handle's
+        // side effects live on `session` (OnToolCall + a finalize-wrapped Close), so the bridge just owns the
+        // session. See plans/realtime/realtime-core-host-convergence.md (Phase 2).
+        await service.WireBridgeRealtimeSession(session, input, prep, contextUser, provider);
+        return session;
+    }
+    /**
+     * Adapts {@link ExecuteAgentParams} → the core {@link PrepareClientSessionInput} for a server-bridged
+     * session. The CO-AGENT is the executed agent; the TARGET agent + the per-session model/voice override
+     * ride `params.data` (the same conduit the native dev picker uses, funneled into the one
+     * `ConfigOverridesJson` cascade slot via {@link BuildRealtimeOverridesJson}). Tools are left empty — a
+     * bridge host injects its OWN UX tools (none for LiveKit audio today); identity/precedence/invoke-target
+     * come from the core. `AgentSessionID` groups this session's observability runs (see
+     * {@link RealtimeClientSessionService.WireBridgeRealtimeSession}).
+     *
+     * @param params The bridge execution parameters.
+     * @returns The core prep input.
+     */
+    buildBridgePrepInput(params) {
+        const modelID = params.data?.realtimeModelID?.trim() || undefined;
+        const voice = params.data?.realtimeVoice?.trim() || undefined;
+        const targetID = params.data?.targetAgentID?.trim() || '';
+        // Multi-agent meeting signal (set by the room coordinator when the agent joins a room that already
+        // has agents): disable the model's blind auto-response + add meeting discipline to the prompt so it
+        // hears everything but speaks only when addressed. SelfNames feed only the prompt phrasing; the
+        // addressing GATE is the bridge's matcher. See plans/realtime/multi-agent-meeting-turn-taking.md.
+        const meetingMode = params.data?.realtimeMeetingMode === true;
+        const selfNames = Array.isArray(params.data?.realtimeSelfNames)
+            ? (params.data?.realtimeSelfNames).filter((n) => typeof n === 'string')
+            : undefined;
+        return {
+            CoAgent: params.agent,
+            TargetAgentID: targetID,
+            AgentSessionID: params.data?.agentSessionId ?? '',
+            PreferredModelID: modelID,
+            ConfigOverridesJson: BuildRealtimeOverridesJson(modelID, voice) ?? undefined,
+            ConversationMessages: params.conversationMessages,
+            UserID: params.contextUser?.ID,
+            DisableAutoResponse: meetingMode || undefined,
+            SelfNames: selfNames,
+        };
+    }
+    /**
+     * Resolves the realtime model + vendor driver + API key for a session-driven run.
+     *
+     * **Overridable seam.** This is the single injection point that test subclasses override to
+     * return a mock {@link BaseRealtimeModel}, so {@link executeRealtimeSession} can be exercised
+     * 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
+     * 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
+     * loop agents use for `ModelSelectionMode`; the AI Agent entity has no direct model FK.)
+     *
+     * @param params The execution parameters (for the agent + context user).
+     * @returns The resolved model instance plus its model/vendor identifiers, or `null`.
+     */
+    async resolveRealtimeModel(params, overrideModelID) {
+        // Walk candidates in resolution order (preference first, then highest PowerRank), returning the
+        // FIRST that FULLY resolves (active vendor + resolvable API key + ClassFactory driver). Single-pick
+        // would dead-end whenever the top model lacked a key — e.g. a power-11 model with no env key
+        // (Inworld/AssemblyAI) outranking GPT Realtime — and surface "No usable Realtime model" even though
+        // a usable model exists. This mirrors the same fix in RealtimeClientSessionService.
+        const candidates = this.selectRealtimeModelCandidates(params.agent, overrideModelID);
+        for (const model of candidates) {
+            const vendor = this.selectRealtimeVendor(model.ID);
+            if (!vendor) {
+                continue;
+            }
+            const apiKey = GetAIAPIKey(vendor.driverClass);
+            if (!apiKey) {
+                continue;
+            }
+            const instance = MJGlobal.Instance.ClassFactory.CreateInstance(BaseRealtimeModel, vendor.driverClass, apiKey);
+            if (!instance) {
+                continue;
+            }
+            return { model: instance, modelID: model.ID, vendorID: vendor.vendorID, apiName: vendor.apiName, driverClass: vendor.driverClass };
+        }
+        return null;
+    }
+    /**
+     * 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
+     * candidates (not just the top pick) so a keyless / undriveable higher-power model falls through to
+     * the next usable one instead of dead-ending the whole resolution.
+     *
+     * Ordering: an effective-config model preference (`realtime.modelPreference`, an MJ: AI Models Name
+     * or ID) goes FIRST when it resolves, followed by the rest by descending PowerRank (so even a keyless
+     * preferred model degrades gracefully). An unsatisfiable preference logs and is ignored.
+     *
+     * @param agent The agent being executed.
+     * @returns The candidate models in resolution order (empty when none are active).
+     */
+    selectRealtimeModelCandidates(agent, overrideModelID) {
+        const isRealtime = (m) => typeof m.AIModelType === 'string' && m.AIModelType.trim().toLowerCase() === 'realtime';
+        const realtimeModels = AIEngine.Instance.Models.filter(m => m.IsActive && isRealtime(m));
+        if (realtimeModels.length === 0) {
+            return [];
+        }
+        const byPower = [...realtimeModels].sort((a, b) => (b.PowerRank ?? 0) - (a.PowerRank ?? 0));
+        // A per-session override (a dev picking a specific Realtime model for this bridged agent) wins over
+        // the config's modelPreference — same "preferred first, rest by power as fallback" semantics.
+        const preference = (overrideModelID && overrideModelID.trim().length > 0)
+            ? overrideModelID.trim()
+            : this.resolveRealtimeEffectiveConfig(agent).realtime?.modelPreference;
+        if (preference) {
+            const wanted = preference.trim().toLowerCase();
+            const preferred = realtimeModels.find(m => UUIDsEqual(m.ID, preference))
+                ?? realtimeModels.find(m => m.Name?.trim().toLowerCase() === wanted);
+            if (preferred) {
+                // Preference first, the rest (by power) as fallback so a keyless preferred model still
+                // falls through to a usable one rather than dead-ending.
+                return [preferred, ...byPower.filter(m => !UUIDsEqual(m.ID, preferred.ID))];
+            }
+            this.logError(`Realtime model preference '${preference}' for agent '${agent.Name}' matches no Active Realtime ` +
+                'model — falling through to default (highest-PowerRank) selection.', { agent, category: 'RealtimeSession' });
+        }
+        return byPower;
+    }
+    /**
+     * Resolves the agent's EFFECTIVE realtime configuration — the agent TYPE's
+     * `DefaultConfiguration` (base layer) deep-merged with the agent's `TypeConfiguration`
+     * (per-agent layer; the server-bridged path has no runtime-override layer). Tolerant:
+     * malformed layers contribute nothing and an unloaded type cache yields no type defaults.
+     * See `realtime/realtime-coagent-config.ts` for the merge contract.
+     *
+     * @param agent The session-driven (Realtime) agent.
+     * @returns The normalized effective configuration (possibly empty, never `null`).
+     */
+    resolveRealtimeEffectiveConfig(agent) {
+        let typeDefault = null;
+        try {
+            if (agent.TypeID) {
+                const type = (AIEngine.Instance.AgentTypes ?? []).find(t => UUIDsEqual(t.ID, agent.TypeID));
+                typeDefault = type?.DefaultConfiguration ?? null;
+            }
+        }
+        catch {
+            typeDefault = null;
+        }
+        return ResolveEffectiveRealtimeConfig(typeDefault, agent.TypeConfiguration ?? null, null);
+    }
+    /**
+     * Selects the highest-priority active vendor for a model whose `DriverClass` has a resolvable
+     * API key. Mirrors the vendor-selection pattern used by prompt execution.
+     *
+     * @param modelID The chosen model's ID.
+     * @returns The vendor driver/api identifiers, or `null` when none has a usable key.
+     */
+    selectRealtimeVendor(modelID) {
+        const vendors = AIEngine.Instance.ModelVendors
+            .filter(mv => UUIDsEqual(mv.ModelID, modelID) && mv.Status === 'Active' && mv.DriverClass != null)
+            .sort((a, b) => (b.Priority ?? 0) - (a.Priority ?? 0));
+        for (const v of vendors) {
+            if (GetAIAPIKey(v.DriverClass)) {
+                return { vendorID: v.VendorID ?? '', driverClass: v.DriverClass, apiName: v.APIName ?? '' };
+            }
+        }
+        return null;
+    }
+    /**
+     * Creates the single long-lived `AIPromptRun` that realtime usage is checkpointed onto.
+     *
+     * One run is created per session (not per turn) so {@link RealtimeSessionRunnerDeps.CheckpointUsage}
+     * can incrementally update the same record — crash-safe by design. Returns `null` on failure;
+     * the session still runs (usage checkpoints simply become no-ops).
+     *
+     * @param params The execution parameters.
+     * @param config The agent configuration (provides the system prompt id, if any).
+     * @param modelResolution The resolved model/vendor identifiers.
+     * @returns The persisted prompt run, or `null` if it could not be created.
+     */
+    async createRealtimePromptRun(params, config, modelResolution) {
+        try {
+            const md = params.provider || this._activeProvider;
+            const promptRun = await md.GetEntityObject('MJ: AI Prompt Runs', params.contextUser);
+            promptRun.NewRecord();
+            if (config.systemPrompt) {
+                promptRun.PromptID = config.systemPrompt.ID;
+            }
+            promptRun.ModelID = modelResolution.modelID;
+            promptRun.VendorID = modelResolution.vendorID || null;
+            promptRun.AgentID = params.agent.ID;
+            promptRun.AgentRunID = this._agentRun?.ID ?? null;
+            promptRun.Status = 'Running';
+            promptRun.RunAt = new Date();
+            promptRun.StreamingEnabled = true;
+            promptRun.Cancelled = false;
+            promptRun.CacheHit = false;
+            if (!await promptRun.Save()) {
+                this.logError(`Failed to create realtime AIPromptRun: ${promptRun.LatestResult?.CompleteMessage ?? 'unknown error'}`, {
+                    agent: params.agent,
+                    category: 'RealtimeSession'
+                });
+                return null;
+            }
+            return promptRun;
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            this.logError(`Error creating realtime AIPromptRun: ${msg}`, { agent: params.agent, category: 'RealtimeSession' });
+            return null;
+        }
+    }
+    /**
+     * Builds the fully-populated {@link RealtimeSessionRunnerDeps} from this agent's collaborators.
+     *
+     * Each dependency is a thin closure over BaseAgent state so the runner stays decoupled from
+     * metadata/DB. The closures cover: target delegation (via {@link ExecuteSubAgent}), non-target
+     * tool execution, transcript persistence (as `ConversationDetail`), and usage checkpointing
+     * (onto the long-lived prompt run).
+     *
+     * @param params The execution parameters.
+     * @param config The agent configuration.
+     * @param modelResolution The resolved realtime model + identifiers.
+     * @param promptRun The long-lived prompt run for usage checkpoints (may be `null`).
+     * @returns The assembled deps object.
+     */
+    async buildRealtimeSessionDeps(params, config, modelResolution, promptRun) {
+        const effectiveConfig = this.resolveRealtimeEffectiveConfig(params.agent);
+        const sessionParams = await this.buildRealtimeSessionParams(params, config, modelResolution.apiName, effectiveConfig, modelResolution.driverClass);
+        return {
+            Model: modelResolution.model,
+            SessionParams: sessionParams,
+            DelegateToTarget: (request) => this.delegateRealtimeToTarget(params, config, request),
+            ExecuteTool: (call) => this.executeRealtimeTool(params, call),
+            PersistTranscript: (transcript) => this.persistRealtimeTranscript(params, transcript),
+            CheckpointUsage: (usage) => this.checkpointRealtimeUsage(promptRun, usage),
+            // DB-driven spoken-progress wording (shared lookup with the client-direct path);
+            // null → the runner's documented built-in first-person fallback.
+            NarrationInstructionsTemplate: ResolveNarrationInstructionsTemplate(),
+            // Effective-config narration pacing (realtime.narration.paceMs); null → runner default.
+            NarrationPaceMs: GetNarrationPaceMs(effectiveConfig),
+            LogStatus: (message, verboseOnly) => this.logStatus(message, verboseOnly ?? false, params),
+            LogError: (error) => this.logError(error, { agent: params.agent, category: 'RealtimeSession' })
+        };
+    }
+    /**
+     * Assembles the {@link RealtimeSessionParams} for the session.
+     *
+     * The system prompt is framed as a companion "voice for the target agent". The base system
+     * prompt text (when an agent-level system prompt exists) plus the same memory/context a loop
+     * agent would assemble (via {@link AgentMemoryContextBuilder}) are concatenated. The
+     * always-present `invoke-target-agent` tool is added by the runner itself, so it is NOT
+     * populated here.
+     *
+     * @param params The execution parameters.
+     * @param config The agent configuration.
+     * @param modelApiName The vendor API name of the resolved realtime model.
+     * @returns The session parameters.
+     */
+    async buildRealtimeSessionParams(params, config, modelApiName, effectiveConfig, driverClass) {
+        // Identity framing comes from the ONE shared producer so the agent speaks first-person AS the
+        // TARGET (Sage / Marketing Agent / …), identical to every other realtime host — not as the co-agent.
+        // See BuildRealtimeAgentFraming + plans/realtime/realtime-core-host-convergence.md.
+        const targetAgent = this.resolveRealtimeTargetAgent(params);
+        const framing = BuildRealtimeAgentFraming(targetAgent?.Name ?? 'the configured target agent');
+        const basePrompt = config.systemPrompt?.TemplateText ? config.systemPrompt.TemplateText : '';
+        // Effective-config voice persona (realtime.voice.default) → short "Voice & manner" section.
+        const voiceManner = BuildVoiceMannerSection(effectiveConfig);
+        const memoryContext = await this.assembleRealtimeContext(params);
+        const systemPrompt = [framing, basePrompt, voiceManner, memoryContext]
+            .filter(part => part && part.trim().length > 0)
+            .join('\n\n');
+        // Provider-matched voice settings (realtime.voice.providers.<provider>) flow into the
+        // driver's open Config bag — the same pact every other config entry rides.
+        const providerVoice = GetProviderVoiceSettings(effectiveConfig, driverClass ?? null);
+        return {
+            Model: modelApiName,
+            SystemPrompt: systemPrompt,
+            InitialContext: memoryContext || undefined,
+            // JSONObjectLike -> JSONObject: safe — the settings object came from JSON.parse.
+            Config: providerVoice ? providerVoice : undefined
+        };
+    }
+    /**
+     * Assembles the same memory/context block a loop agent injects, reusing
+     * {@link AgentMemoryContextBuilder} so there is no duplicated retrieval logic. The builder
+     * unshifts a system message onto a throwaway array, which we pull back out as plain text to
+     * feed the realtime model's session context.
+     *
+     * @param params The execution parameters.
+     * @returns The concatenated context text (empty string when nothing was injected).
+     */
+    async assembleRealtimeContext(params) {
+        const lastUserMessage = params.conversationMessages.filter(m => m.role === 'user').pop();
+        const inputText = typeof lastUserMessage?.content === 'string' ? lastUserMessage.content : '';
+        const scratch = [];
+        const builder = new AgentMemoryContextBuilder();
+        await builder.InjectContextMemory(inputText, params.agent, params.userId || params.contextUser?.ID, params.companyId, params.contextUser, scratch, undefined, undefined, undefined, null, undefined, (message, verboseOnly) => this.logStatus(message, verboseOnly ?? false, params));
+        return scratch
+            .map(m => (typeof m.content === 'string' ? m.content : ''))
+            .filter(c => c.length > 0)
+            .join('\n\n');
+    }
+    /**
+     * Delegates an `invoke-target-agent` tool call to the top-level target agent.
+     *
+     * Threads the runner-owned {@link DelegateToTargetRequest.AbortSignal} into the child run's
+     * `cancellationToken` (so barge-in cancels the delegated work), and links the child run to this
+     * run via `parentRun` (→ `ParentRunID`) while propagating `agentSessionID` so both runs group
+     * under the same session.
+     *
+     * **Target source.** The target agent id comes from `params.data.targetAgentID` when present
+     * (the Realtime Co-Agent receives its target as a runtime parameter), falling back to the agent's
+     * own `DefaultModelID`-style config is NOT applicable here; absent a target the delegation
+     * returns a failed {@link DelegatedResult} the model can narrate.
+     *
+     * @param params The (parent) execution parameters.
+     * @param config The agent configuration (unused today; reserved for target-from-config wiring).
+     * @param request The delegation request derived from the tool call.
+     * @returns The delegated result for the model's tool_response.
+     */
+    async delegateRealtimeToTarget(params, config, request) {
+        const targetAgent = this.resolveRealtimeTargetAgent(params);
+        if (!targetAgent) {
+            return {
+                CallID: request.CallID,
+                Success: false,
+                Output: 'No target agent is configured for this voice session, so the request could not be performed.'
+            };
+        }
+        try {
+            const requestText = this.parseDelegateRequestText(request.Arguments);
+            const runner = new AgentRunner(params.provider || this._activeProvider);
+            const result = await runner.RunAgent({
+                agent: targetAgent,
+                conversationMessages: [{ role: 'user', content: requestText }],
+                contextUser: params.contextUser,
+                cancellationToken: request.AbortSignal,
+                parentRun: this._agentRun ?? undefined,
+                agentSessionID: params.agentSessionID,
+                parentAgentHierarchy: this._agentHierarchy,
+                parentDepth: this._depth,
+                configurationId: params.configurationId,
+                apiKeys: params.apiKeys,
+                data: params.data,
+                verbose: params.verbose,
+                // Progress streams BOTH to the runner's narration consumer (request.OnProgress —
+                // it paces SendContextNote/RequestSpokenUpdate over the live socket) AND to any
+                // host-level onProgress the parent execution carries.
+                onProgress: this.combineProgressCallbacks(request.OnProgress, params.onProgress)
+            });
+            return {
+                CallID: request.CallID,
+                Success: result.success,
+                Output: result.success
+                    ? (result.agentRun?.Message || 'The target agent completed the request.')
+                    : (result.agentRun?.ErrorMessage || 'The target agent failed to complete the request.')
+            };
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            return { CallID: request.CallID, Success: false, Output: `Delegation failed: ${msg}` };
+        }
+    }
+    /**
+     * Combines the runner-supplied delegation progress callback with the host-level one so a
+     * single `onProgress` fans out to both. Returns the lone callback when only one exists, and
+     * `undefined` when neither does. A throw from one consumer never starves the other.
+     */
+    combineProgressCallbacks(first, second) {
+        if (!first) {
+            return second;
+        }
+        if (!second) {
+            return first;
+        }
+        return (progress) => {
+            try {
+                first(progress);
+            }
+            catch {
+                /* one consumer failing must not starve the other */
+            }
+            second(progress);
+        };
+    }
+    /**
+     * Resolves the top-level target agent for the voice session.
+     *
+     * The target is supplied as a runtime parameter on `params.data.targetAgentID` (the Voice
+     * Co-Agent voices on behalf of a target chosen at session start). Returns `null` when no
+     * resolvable target is configured.
+     *
+     * @param params The execution parameters.
+     * @returns The target agent entity, or `null`.
+     */
+    resolveRealtimeTargetAgent(params) {
+        const targetID = params.data?.targetAgentID;
+        if (!targetID) {
+            return null;
+        }
+        return AIEngine.Instance.Agents.find(a => UUIDsEqual(a.ID, targetID)) ?? null;
+    }
+    /**
+     * Parses the natural-language request text out of an `invoke-target-agent` call's arguments.
+     * Falls back to the raw argument string when it is not the expected `{ request: string }` JSON.
+     *
+     * @param argumentsJson The raw arguments string emitted by the model.
+     * @returns The request text to hand to the target agent.
+     */
+    parseDelegateRequestText(argumentsJson) {
+        try {
+            const parsed = JSON.parse(argumentsJson);
+            if (typeof parsed.request === 'string') {
+                return parsed.request;
+            }
+        }
+        catch {
+            /* not JSON — fall through to raw */
+        }
+        return argumentsJson;
+    }
+    /**
+     * Executes a non-target realtime tool call by routing it through the agent's existing action
+     * execution under the session context user.
+     *
+     * Today this maps the realtime call onto the agent's configured actions by name; unknown tools
+     * return a failed {@link ToolExecutionResult} the model can narrate. (The richer client/UI tool
+     * routing is wired in a later phase; this keeps server actions usable now.)
+     *
+     * @param params The execution parameters.
+     * @param call The non-target tool call.
+     * @returns The tool execution result for the model's tool_response.
+     */
+    async executeRealtimeTool(params, call) {
+        const action = this.getEffectiveActionsForValidation(params.agent.ID).find(a => a.Name === call.ToolName);
+        if (!action) {
+            return {
+                CallID: call.CallID,
+                Success: false,
+                Output: `Tool '${call.ToolName}' is not available to this agent.`
+            };
+        }
+        try {
+            const agentAction = { name: action.Name, params: this.parseRealtimeToolParams(call.Arguments) };
+            const result = await this.ExecuteSingleAction(params, agentAction, action, params.contextUser);
+            return {
+                CallID: call.CallID,
+                Success: result.Success,
+                Output: result.Message || (result.Success ? 'Tool completed.' : 'Tool failed.')
+            };
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            return { CallID: call.CallID, Success: false, Output: `Tool execution failed: ${msg}` };
+        }
+    }
+    /**
+     * Parses a realtime tool call's JSON arguments into an action parameter map.
+     *
+     * @param argumentsJson The raw arguments string.
+     * @returns A record of parameter name → value (empty when not parseable).
+     */
+    parseRealtimeToolParams(argumentsJson) {
+        try {
+            const parsed = JSON.parse(argumentsJson);
+            if (parsed && typeof parsed === 'object') {
+                return parsed;
+            }
+        }
+        catch {
+            /* ignore — return empty params */
+        }
+        return {};
+    }
+    /**
+     * Persists a single realtime transcript turn as a `ConversationDetail` stamped with the
+     * session id. User turns are written as `Role='User'`, assistant turns as `Role='AI'`. Only
+     * final transcripts are persisted (interim/partial updates are skipped to avoid churn).
+     *
+     * @param params The execution parameters (provides conversation id + context user).
+     * @param transcript The transcript turn emitted by the model.
+     */
+    async persistRealtimeTranscript(params, transcript) {
+        if (!transcript.IsFinal || !transcript.Text?.trim()) {
+            return;
+        }
+        const conversationID = params.data?.conversationId;
+        if (!conversationID) {
+            return; // Without a conversation we have nowhere to durably attach the turn.
+        }
+        const md = params.provider || this._activeProvider;
+        const detail = await md.GetEntityObject('MJ: Conversation Details', params.contextUser);
+        detail.NewRecord();
+        detail.ConversationID = conversationID;
+        detail.Role = transcript.Role === 'user' ? 'User' : 'AI';
+        detail.Message = transcript.Text;
+        if (params.agentSessionID) {
+            detail.AgentSessionID = params.agentSessionID;
+        }
+        if (!await detail.Save()) {
+            this.logError(`Failed to persist realtime transcript turn: ${detail.LatestResult?.CompleteMessage ?? 'unknown error'}`, {
+                agent: params.agent,
+                category: 'RealtimeSession'
+            });
+        }
+    }
+    /**
+     * Checkpoints accumulated realtime usage onto the single long-lived prompt run. This is the
+     * incremental, crash-safe write the runner invokes on a debounced cadence and at close.
+     *
+     * @param promptRun The long-lived prompt run (no-op when `null`).
+     * @param usage The cumulative usage snapshot to persist.
+     */
+    async checkpointRealtimeUsage(promptRun, usage) {
+        if (!promptRun) {
+            return;
+        }
+        promptRun.TokensPrompt = usage.InputTokens;
+        promptRun.TokensCompletion = usage.OutputTokens;
+        promptRun.TokensUsed = usage.InputTokens + usage.OutputTokens;
+        if (!await promptRun.Save()) {
+            this.logError(`Failed to checkpoint realtime usage: ${promptRun.LatestResult?.CompleteMessage ?? 'unknown error'}`, {
+                category: 'RealtimeSession'
+            });
+        }
+    }
+    /**
+     * Maps a completed {@link RealtimeSessionResult} onto the finalized `AIAgentRun` and returns
+     * the {@link ExecuteAgentResult}. A clean close finalizes as success; a session error finalizes
+     * as failure with the error message.
+     *
+     * @template R The caller's payload type (unused on the realtime path).
+     * @param params The execution parameters.
+     * @param sessionResult The result returned by {@link RealtimeSessionRunner.Run}.
+     * @returns The finalized agent result.
+     */
+    async finalizeRealtimeRun(params, sessionResult) {
+        if (sessionResult.Success) {
+            this.logStatus(`🎙️ Realtime session for '${params.agent.Name}' completed: ${sessionResult.TranscriptTurnCount} turn(s), ` +
+                `${sessionResult.FinalUsage.InputTokens + sessionResult.FinalUsage.OutputTokens} token(s).`, true, params);
+            const successStep = this.createSessionSuccessStep();
+            return await this.finalizeAgentRun(successStep, undefined, params.contextUser);
+        }
+        const message = sessionResult.ErrorMessage || 'Realtime session ended with an error.';
+        return await this.createFailureResult(message, params.contextUser);
+    }
+    /**
+     * Builds a terminal `Success` step describing the completion of a realtime session, used to
+     * finalize the run through the shared {@link finalizeAgentRun} path.
+     *
+     * @template R The caller's payload type.
+     * @returns A terminal success step.
+     */
+    createSessionSuccessStep() {
+        return {
+            step: 'Success',
+            terminate: true,
+            message: 'Realtime session completed.'
+        };
+    }
     /**
      * Sub-classes can override this method to perform any specialized initialization
      * @param params
@@ -1338,8 +2022,13 @@ export class BaseAgent {
      * @protected
      */
     async initializeEngines(contextUser) {
-        await AIEngine.Instance.Config(false, contextUser);
+        // Load the Action engine BEFORE the AI engine. AIEngine.RefreshActions()
+        // (invoked by AIEngine.Config) reuses already-cached 'MJ: Actions'
+        // metadata via BaseEngineRegistry, so priming ActionEngineServer first
+        // lets AIEngine skip loading a second copy into ActionEngineBase —
+        // eliminating the duplicate-RunView telemetry warning at agent startup.
         await ActionEngineServer.Instance.Config(false, contextUser);
+        await AIEngine.Instance.Config(false, contextUser);
     }
     /**
      * Determine the scope label for a note based on its scope fields.
@@ -1393,72 +2082,16 @@ export class BaseAgent {
      * @returns Object containing injected notes and examples
      */
     async InjectContextMemory(input, agent, userId, companyId, contextUser, conversationMessages, primaryScopeEntityId, primaryScopeRecordId, secondaryScopes, secondaryScopeConfig) {
-        // Check if injection is enabled
-        if (!agent.InjectNotes && !agent.InjectExamples) {
-            return { notes: [], examples: [] };
-        }
-        const injector = new AgentContextInjector();
-        // Parse reranker configuration if present
-        const rerankerConfigJson = agent.RerankerConfiguration;
-        const rerankerConfig = RerankerService.Instance.parseConfiguration(rerankerConfigJson);
-        // Get notes if injection enabled
-        const notes = agent.InjectNotes
-            ? await injector.GetNotesForContext({
-                agentId: agent.ID,
-                userId,
-                companyId,
-                currentInput: input,
-                strategy: agent.NoteInjectionStrategy,
-                maxNotes: agent.MaxNotesToInject || 5,
-                contextUser: contextUser,
-                rerankerConfig,
-                primaryScopeEntityId,
-                primaryScopeRecordId,
-                secondaryScopes,
-                secondaryScopeConfig,
-                // Pass observability context for run step tracking
-                observability: this._agentRun ? {
-                    agentRunID: this._agentRun.ID,
-                    stepNumber: (this._agentRun.Steps?.length || 0) + 1
-                } : undefined
-            })
-            : [];
-        this.logStatus(`BaseAgent: Got ${notes.length} notes from injector`, true);
-        // Get examples if injection enabled
-        const examples = agent.InjectExamples
-            ? await injector.GetExamplesForContext({
-                agentId: agent.ID,
-                userId,
-                companyId,
-                currentInput: input,
-                strategy: agent.ExampleInjectionStrategy,
-                maxExamples: agent.MaxExamplesToInject || 3,
-                contextUser: contextUser,
-                primaryScopeEntityId,
-                primaryScopeRecordId,
-                secondaryScopes,
-                secondaryScopeConfig
-            })
-            : [];
-        // Format and inject memory context into conversation messages
-        if ((notes.length > 0 || examples.length > 0) && conversationMessages) {
-            const notesText = injector.FormatNotesForInjection(notes);
-            const examplesText = injector.FormatExamplesForInjection(examples);
-            this._memoryContext = '';
-            if (notesText)
-                this._memoryContext += notesText + '\n\n';
-            if (examplesText)
-                this._memoryContext += examplesText + '\n\n';
-            // Inject as system message at the start
-            conversationMessages.unshift({
-                role: 'system',
-                content: this._memoryContext
-            });
-            this.logStatus(`💾 Injected ${notes.length} notes and ${examples.length} examples into conversation context`, true);
-        }
-        // Store for inclusion in result
-        this._injectedMemory = { notes, examples };
-        return { notes, examples };
+        // Delegate the orchestration to the shared, reusable builder so both BaseAgent and the
+        // Realtime agent type inject memory identically. The observability context and verbose
+        // status logging are derived from this instance and passed through.
+        const observability = this._agentRun
+            ? { agentRunID: this._agentRun.ID, stepNumber: (this._agentRun.Steps?.length || 0) + 1 }
+            : undefined;
+        const result = await new AgentMemoryContextBuilder().InjectContextMemory(input, agent, userId, companyId, contextUser, conversationMessages, primaryScopeEntityId, primaryScopeRecordId, secondaryScopes, secondaryScopeConfig, observability, (message, verboseOnly) => this.logStatus(message, verboseOnly));
+        // Store for inclusion in result (externally observable behavior preserved)
+        this._injectedMemory = result;
+        return result;
     }
     /**
      * Inject pre-execution RAG context for this agent using scoped search.
@@ -1486,40 +2119,12 @@ export class BaseAgent {
      * @returns The structured RAG result, or `null` if no scopes produced results.
      */
     async InjectPreExecutionRAG(lastUserMessage, agent, contextUser, conversationMessages, originalMessages, primaryScopeEntityId, primaryScopeRecordId, secondaryScopes, payload) {
-        try {
-            if (!contextUser)
-                return null;
-            if (!agent?.ID)
-                return null;
-            const rag = new AgentPreExecutionRAG();
-            const result = await rag.Execute({
-                agent,
-                lastUserMessage,
-                recentMessages: originalMessages ? originalMessages.slice(-5) : undefined,
-                payload,
-                primaryScopeRecordId,
-                primaryScopeEntityId,
-                secondaryScopes,
-                contextUser
-            });
-            if (!result)
-                return null;
-            if (conversationMessages && result.formattedSystemMessage) {
-                this._ragContext = result.formattedSystemMessage;
-                conversationMessages.unshift({ role: 'system', content: this._ragContext });
-                this.logStatus(`🔎 Injected pre-execution RAG context: ${result.combinedResults.length} result(s) from ${result.queriedScopeIDs.length} scope(s)`, true);
-            }
-            this._injectedRAG = result;
-            return result;
-        }
-        catch (error) {
-            const msg = error instanceof Error ? error.message : String(error);
-            this.logError(`InjectPreExecutionRAG failed — continuing without RAG context: ${msg}`, {
-                agent,
-                category: 'AgentPreExecutionRAG'
-            });
-            return null;
-        }
+        // Delegate to the shared builder so the Realtime agent type injects pre-execution RAG
+        // identically. Verbose status + non-fatal error logging are threaded through from this instance.
+        const result = await new AgentMemoryContextBuilder().InjectPreExecutionRAG(lastUserMessage, agent, contextUser, conversationMessages, originalMessages, primaryScopeEntityId, primaryScopeRecordId, secondaryScopes, payload, (message, verboseOnly) => this.logStatus(message, verboseOnly), (error, options) => this.logError(error, options));
+        // Store for inclusion in result (externally observable behavior preserved)
+        this._injectedRAG = result;
+        return result;
     }
     /**
      * Converts UI markup (@{...} syntax) in user messages to plain text.
@@ -1793,7 +2398,7 @@ export class BaseAgent {
         const systemPrompt = config.systemPrompt;
         const childPrompt = config.childPrompt;
         // Gather context data (including runtime action changes)
-        const promptTemplateData = await this.gatherPromptTemplateData(params.agent, params.contextUser, params.data, params.actionChanges);
+        const promptTemplateData = await this.gatherPromptTemplateData(params.agent, params.contextUser, params.data, params.actionChanges, params.subAgentChanges);
         // Set up the hierarchical prompt execution
         const promptParams = new AIPromptParams();
         // Handle case where systemPrompt is optional (e.g., Flow Agent Type)
@@ -1868,6 +2473,13 @@ export class BaseAgent {
             else if (this._artifactToolManager.HasArtifacts()) {
                 this.logStatus(`[ArtifactTools] Artifacts present but tools disabled by agent config (includeArtifactToolsDocs=false)`, true, params);
             }
+            // Enable the memory-writes response field + docs only for agents that opted in
+            // via AllowMemoryWrite. Disabled agents never see the docs, so a well-behaved
+            // LLM never emits the field (the turn loop still guards against drift).
+            const memoryWritesDocsEnabled = agentTypePromptParams?.includeMemoryWritesDocs !== false;
+            if (memoryWritesDocsEnabled && params.agent.AllowMemoryWrite === true) {
+                promptParams.data['_MEMORY_WRITES_ENABLED'] = true;
+            }
             // Inject pipeline tool docs when pipelines are enabled and at least one source exists.
             // A pipeline's first step must be a source (Action or artifact tool); with none
             // available pipelines are impossible, so BuildPipelineToolDocs returns '' and the
@@ -3433,6 +4045,129 @@ The context is now within limits. Please retry your request with the recovered c
             `Instead: page it with get_rows(start, count), or run a pipeline that filters/aggregates it ` +
             `server-side (where / select / groupBy → only the small final result returns to you).]`);
     }
+    /**
+     * Executes a batch of in-flight memory writes, recording each as its own
+     * `Tool` AIAgentRunStep (a sibling of the Prompt step that requested them)
+     * with full inputs/outcomes captured in InputData/OutputData.
+     *
+     * Writes run SEQUENTIALLY (not Promise.all like artifact tools) by design:
+     * each persisted note is embedded and synced into the in-memory vector
+     * service on Save, so write N must be visible to write N+1's near-duplicate
+     * check (this is also what makes same-run supersede-own work). The per-run
+     * cap bounds the cost of the serialization.
+     *
+     * Step naming convention: `Memory Write` for log/UI clarity.
+     *
+     * @protected
+     */
+    async executeMemoryWritesAsSteps(writes, params) {
+        const results = [];
+        for (const write of writes) {
+            const writeStep = await this.createStepEntity({
+                stepType: 'Tool',
+                stepName: 'Memory Write',
+                contextUser: params.contextUser,
+                inputData: {
+                    note: write.note,
+                    type: write.type,
+                    scopeHint: write.scopeHint,
+                },
+            });
+            const result = await this._memoryWriteManager.ExecuteWrite(write, {
+                agentId: params.agent.ID,
+                contextUser: params.contextUser,
+                agentRunId: this._agentRun?.ID,
+                conversationId: this._agentRun?.ConversationID || undefined,
+                conversationDetailId: params.conversationDetailId,
+                userId: params.userId || params.contextUser?.ID,
+                companyId: params.companyId,
+                verbose: params.verbose,
+                provider: this.ProviderToUse,
+            });
+            const failed = result.disposition === 'error' || result.disposition === 'rejected-type';
+            await this.finalizeStepEntity(writeStep, !failed, failed ? result.reason : undefined, {
+                disposition: result.disposition,
+                noteId: result.noteId,
+                finalScope: result.finalScope,
+                reason: result.reason,
+                durationMs: result.durationMs,
+            });
+            results.push(result);
+        }
+        return results;
+    }
+    /**
+     * Turn-loop entry point for in-flight memory writes, gated on the agent's
+     * AllowMemoryWrite flag. When disabled but the LLM emitted writes anyway
+     * (prompt drift / injection attempt), records ONE summary skip step —
+     * observable without per-write noise — and tells the agent the memories
+     * were NOT saved so it stops re-emitting. When enabled, executes the
+     * writes as run steps and injects the results message.
+     *
+     * @protected
+     */
+    async processMemoryWritesForTurn(memoryWrites, params) {
+        if (params.agent.AllowMemoryWrite !== true) {
+            this.logStatus(`[MemoryWrites] LLM emitted ${memoryWrites.length} memory write(s) but AllowMemoryWrite=false — skipping`, true, params);
+            const skipStep = await this.createStepEntity({
+                stepType: 'Tool',
+                stepName: 'Memory Writes: skipped (AllowMemoryWrite=false)',
+                contextUser: params.contextUser,
+                inputData: { requestedWriteCount: memoryWrites.length },
+            });
+            await this.finalizeStepEntity(skipStep, true, undefined, { skipped: true, reason: 'AllowMemoryWrite=false' });
+            params.conversationMessages.push({
+                role: 'user',
+                content: 'Memory write result: this agent does not have durable memory writes enabled — the requested memories were NOT saved. Do not emit memoryWrites again.',
+                metadata: {
+                    turnAdded: this._promptTurnCount,
+                    messageType: 'tool-result',
+                    expirationTurns: 3,
+                    expirationMode: 'Compact',
+                    compactMode: 'First N Chars',
+                    compactLength: 200,
+                    compactPromptId: '',
+                },
+            });
+            return;
+        }
+        this.logStatus(`[MemoryWrites] LLM requested ${memoryWrites.length} memory write(s)`, true, params);
+        const writeResults = await this.executeMemoryWritesAsSteps(memoryWrites, params);
+        this.injectMemoryWriteResultsMessage(params, writeResults);
+    }
+    /**
+     * Pushes a single user-role message containing memory-write outcomes into
+     * the conversation, mirroring `injectArtifactToolResultsMessage`'s
+     * inject-once-then-expire pattern. Closing the loop here is what stops the
+     * LLM from re-emitting the same memory on subsequent turns.
+     *
+     * @protected
+     */
+    injectMemoryWriteResultsMessage(params, results) {
+        if (results.length === 0)
+            return;
+        const header = results.length === 1
+            ? 'Memory write result:'
+            : `Memory write results (${results.length} writes):`;
+        const body = results.map((r, i) => {
+            const note = r.request.note.length > 120 ? `${r.request.note.slice(0, 120)}…` : r.request.note;
+            return `${i + 1}. "${note}" — **${r.disposition}**${r.reason ? `: ${r.reason}` : ''}`;
+        }).join('\n');
+        const message = {
+            role: 'user',
+            content: `${header}\n${body}`,
+            metadata: {
+                turnAdded: this._promptTurnCount,
+                messageType: 'tool-result',
+                expirationTurns: 3,
+                expirationMode: 'Compact',
+                compactMode: 'First N Chars',
+                compactLength: 300,
+                compactPromptId: '',
+            },
+        };
+        params.conversationMessages.push(message);
+    }
     /**
      * Builds a per-run {@link PipelineToolRegistry} that unifies the three pipeline-able
      * substrates behind one namespace: built-in transforms, the agent's effective Actions, and
@@ -3583,37 +4318,70 @@ The context is now within limits. Please retry your request with the recovered c
      *
      * @private
      */
-    async gatherPromptTemplateData(agent, _contextUser, extraData, actionChanges) {
+    async gatherPromptTemplateData(agent, _contextUser, extraData, actionChanges, subAgentChanges) {
         try {
             const engine = AIEngine.Instance;
-            // Find sub-agents using AIEngine
-            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');
-            // now combine the child sub-agents from the direct parentID relationships with the agentRelationships array, distinct to not repeat
-            // unique ID values
-            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)));
-            // Load available actions from database configuration
-            const agentActions = engine.AgentActions.filter(aa => UUIDsEqual(aa.AgentID, agent.ID) && aa.Status === 'Active');
-            let actions = ActionEngineServer.Instance.Actions.filter(a => agentActions.some(aa => UUIDsEqual(aa.ActionID, a.ID)));
-            // Apply runtime action changes if provided
+            // Build (or reuse) the agent-invariant base catalog. This is process-wide cached on
+            // AIEngine and wiped on Agent/AgentAction/AgentRelationship/AgentType changes + reloads.
+            // It turns the per-step rebuild (sub-agent + action resolution, markdown, JSON.parse of
+            // agent-type params) into a once-per-agent cost; the common no-override step reuses it wholesale.
+            let catalog = engine.GetAgentBaseCatalog(agent.ID);
+            if (!catalog) {
+                catalog = this.buildAgentBaseCatalog(agent, engine);
+                engine.SetAgentBaseCatalog(agent.ID, catalog);
+            }
+            const isRoot = this._depth === 0;
+            // Sub-agents: reuse cached base unless runtime subAgentChanges apply (then clone + re-format).
+            let uniqueActiveSubAgents = catalog.uniqueActiveSubAgents;
+            let subAgentDetails = catalog.subAgentDetails;
+            let subAgentCount = catalog.subAgentCount;
+            if (subAgentChanges?.length) {
+                uniqueActiveSubAgents = this.applySubAgentChanges(catalog.uniqueActiveSubAgents, subAgentChanges, agent.ID, isRoot, engine);
+                subAgentCount = uniqueActiveSubAgents.length;
+                subAgentDetails = this.formatSubAgentDetails(uniqueActiveSubAgents);
+            }
+            // Actions: reuse cached active set unless runtime actionChanges apply (then clone + re-format).
+            //
+            // FAST-PATH SHARING CONTRACT: on the no-override path, `activeActions` (and therefore
+            // `_effectiveActions`) and `uniqueActiveSubAgents` above are the SAME array references
+            // held by the process-wide AIEngine catalog cache. Downstream consumers MUST treat them
+            // as read-only — they are only ever read (`.find`/`.map`/`.length`/`.some`), never mutated
+            // in place. On the override path a fresh array is built via filter/applyActionChanges, so
+            // the cached arrays are never the mutated ones. Keeping the references (vs. copying) avoids
+            // a per-step allocation; if a future consumer needs to mutate, it must `.slice()` first.
+            let activeActions = catalog.activeActions;
+            let actionDetails = catalog.actionDetails;
             if (actionChanges?.length) {
-                const isRoot = this._depth === 0;
-                const result = this.applyActionChanges(actions, actionChanges, agent.ID, isRoot);
-                actions = result.actions;
+                const result = this.applyActionChanges([...catalog.baseActionsRaw], actionChanges, agent.ID, isRoot);
+                activeActions = result.actions.filter(a => a.Status === 'Active');
                 this._dynamicActionLimits = result.dynamicLimits;
+                actionDetails = this.formatActionDetails(activeActions);
             }
-            // Filter to only active actions and store for later validation in executeActionsStep
-            const activeActions = actions.filter(a => a.Status === 'Active');
+            else {
+                // No actionChanges this step → no dynamically-added actions, hence no dynamic limits.
+                // gatherPromptTemplateData runs once per step, and _dynamicActionLimits is keyed to the
+                // actionChanges of the CURRENT step (read at validation time in checkActionExecutionLimits).
+                // Resetting to {} is correct and required: it prevents a prior step's actionChanges limits
+                // from leaking into a step that has none. It is NOT relied upon to persist across steps.
+                this._dynamicActionLimits = {};
+            }
+            // Store for later validation in executeActionsStep
             this._effectiveActions = activeActions;
-            // Build agent type prompt params (merged from schema defaults, agent config, and runtime overrides)
-            const agentType = engine.AgentTypes.find(at => UUIDsEqual(at.ID, agent.TypeID));
+            // Agent type prompt params: reuse cached base merge unless a runtime override is present.
             const runtimePromptParamOverrides = extraData?.__agentTypePromptParams;
-            const agentTypePromptParams = this.buildAgentTypePromptParams(agentType, agent, runtimePromptParamOverrides);
-            // Build client tool details for the prompt
+            let agentTypePromptParams;
+            if (runtimePromptParamOverrides) {
+                const agentType = engine.AgentTypes.find(at => UUIDsEqual(at.ID, agent.TypeID));
+                agentTypePromptParams = this.buildAgentTypePromptParams(agentType, agent, runtimePromptParamOverrides);
+            }
+            else {
+                // Fast path: shallow-clone the cached base params before handing them out. The cached
+                // object lives in the process-wide AIEngine catalog and is shared across every run of
+                // this agent; the audit shows it is read-only downstream today, but the clone is cheap
+                // and removes any cache-poisoning foot-gun should a future consumer write to it.
+                agentTypePromptParams = { ...catalog.baseAgentTypePromptParams };
+            }
+            // Build client tool details for the prompt (per-run; depends on extraData)
             const clientToolDetails = this.buildClientToolPromptSection(agent, extraData);
             // Build app context section if provided in extraData
             const appContext = this.buildAppContextSection(extraData);
@@ -3621,10 +4389,10 @@ The context is now within limits. Please retry your request with the recovered c
                 agentName: agent.Name,
                 agentDescription: agent.Description,
                 parentAgentName: agent.Parent ? agent.Parent.trim() : "",
-                subAgentCount: uniqueActiveSubAgents.length,
-                subAgentDetails: this.formatSubAgentDetails(uniqueActiveSubAgents),
+                subAgentCount: subAgentCount,
+                subAgentDetails: subAgentDetails,
                 actionCount: activeActions.length,
-                actionDetails: this.formatActionDetails(activeActions),
+                actionDetails: actionDetails,
                 clientToolDetails: clientToolDetails,
                 appContext: appContext,
             };
@@ -3656,6 +4424,98 @@ The context is now within limits. Please retry your request with the recovered c
             throw new Error(`Error gathering context data: ${error.message}`);
         }
     }
+    /**
+     * Builds the agent-invariant {@link AgentBaseCatalog} — the resolved sub-agents + actions and
+     * their formatted markdown, plus the base agent-type prompt params. Computed once per agent and
+     * cached on AIEngine (see gatherPromptTemplateData); does NOT apply any runtime overrides.
+     *
+     * @protected
+     */
+    buildAgentBaseCatalog(agent, engine) {
+        // Resolve sub-agents: direct ParentID children + active relationships, de-duped, ordered.
+        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)));
+        // 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)));
+        const activeActions = baseActionsRaw.filter(a => a.Status === 'Active');
+        // Base agent-type prompt params (schema defaults + agent config; NO runtime overrides).
+        const agentType = engine.AgentTypes.find(at => UUIDsEqual(at.ID, agent.TypeID));
+        const baseAgentTypePromptParams = this.buildAgentTypePromptParams(agentType, agent, undefined);
+        return {
+            uniqueActiveSubAgents,
+            subAgentCount: uniqueActiveSubAgents.length,
+            subAgentDetails: this.formatSubAgentDetails(uniqueActiveSubAgents),
+            baseActionsRaw,
+            activeActions,
+            actionDetails: this.formatActionDetails(activeActions),
+            baseAgentTypePromptParams,
+        };
+    }
+    /**
+     * Applies runtime {@link SubAgentChange}s to a base sub-agent set — the sub-agent counterpart of
+     * {@link applyActionChanges}. Returns a NEW array (never mutates the cached base set).
+     *
+     * @protected
+     */
+    applySubAgentChanges(baseSubAgents, subAgentChanges, agentId, isRoot, engine) {
+        let subAgents = [...baseSubAgents];
+        for (const change of subAgentChanges) {
+            if (!this.doesChangeScopeApply(change.scope, agentId, isRoot, change.agentIds)) {
+                continue;
+            }
+            if (change.mode === 'add') {
+                for (const subAgentId of change.subAgentIds) {
+                    if (!subAgents.some(a => UUIDsEqual(a.ID, subAgentId))) {
+                        const toAdd = engine.Agents.find(a => UUIDsEqual(a.ID, subAgentId));
+                        if (toAdd) {
+                            subAgents.push(toAdd);
+                        }
+                        else {
+                            LogStatus(`Sub-agent with ID '${subAgentId}' not found in AIEngine - skipping add`);
+                        }
+                    }
+                }
+            }
+            else if (change.mode === 'remove') {
+                subAgents = subAgents.filter(a => !change.subAgentIds.some(id => UUIDsEqual(id, a.ID)));
+            }
+        }
+        return subAgents;
+    }
+    /**
+     * Filters/transforms sub-agent changes for propagation to a sub-agent — the sub-agent counterpart
+     * of {@link filterActionChangesForSubAgent} (same propagation rules).
+     *
+     * @protected
+     */
+    filterSubAgentChangesForSubAgent(subAgentChanges) {
+        if (!subAgentChanges?.length) {
+            return undefined;
+        }
+        const filtered = [];
+        for (const change of subAgentChanges) {
+            switch (change.scope) {
+                case 'root':
+                    continue; // only applies to root — don't propagate
+                case 'global':
+                    filtered.push(change);
+                    break;
+                case 'all-subagents':
+                    filtered.push({ ...change, scope: 'global' });
+                    break;
+                case 'specific':
+                    filtered.push(change);
+                    break;
+            }
+        }
+        return filtered.length > 0 ? filtered : undefined;
+    }
     /**
      * Builds merged agent type prompt params from schema defaults,
      * agent config, and runtime overrides.
@@ -3743,7 +4603,8 @@ The context is now within limits. Please retry your request with the recovered c
             { docsFlag: 'includeWhileDocs', responseTypeKey: 'while' },
             { docsFlag: 'includeScratchpadDocs', responseTypeKey: 'scratchpad' },
             { docsFlag: 'includeArtifactToolsDocs', responseTypeKey: 'artifactToolCalls' },
-            { docsFlag: 'includePipelineDocs', responseTypeKey: 'pipeline' }
+            { docsFlag: 'includePipelineDocs', responseTypeKey: 'pipeline' },
+            { docsFlag: 'includeMemoryWritesDocs', responseTypeKey: 'memoryWrites' }
         ];
         for (const { docsFlag, responseTypeKey } of alignmentMappings) {
             // Check if the user explicitly set this response type property
@@ -3985,8 +4846,9 @@ The context is now within limits. Please retry your request with the recovered c
                 this.logStatus(`🎯 Propagating effort level ${params.effortLevel} to sub-agent '${subAgentRequest.name}'`, true, params);
             }
             const parentStepCountsToPass = [...this._parentStepCounts, stepCount + 1];
-            // Filter action changes for sub-agent propagation
+            // Filter action / sub-agent changes for sub-agent propagation
             const subAgentActionChanges = this.filterActionChangesForSubAgent(params.actionChanges);
+            const subAgentSubAgentChanges = this.filterSubAgentChangesForSubAgent(params.subAgentChanges);
             // Execute the sub-agent with cancellation and streaming support
             // Use subAgentRequest.context if provided, otherwise fall back to params.context
             // This allows Flow agents and Loop agents to propagate context through sub-agent requests
@@ -4014,12 +4876,15 @@ The context is now within limits. Please retry your request with the recovered c
                 context: subAgentContext, // use subAgentRequest.context if provided, otherwise params.context
                 verbose: params.verbose, // pass verbose flag to sub-agent
                 actionChanges: subAgentActionChanges, // propagate filtered action changes to sub-agent
+                subAgentChanges: subAgentSubAgentChanges, // propagate filtered sub-agent changes to sub-agent
                 PrimaryScopeEntityName: params.PrimaryScopeEntityName, // propagate scope to sub-agent
                 PrimaryScopeRecordID: params.PrimaryScopeRecordID,
                 SecondaryScopes: params.SecondaryScopes,
                 onAgentRunCreated: async (agentRunId) => {
                     stepEntity.TargetLogID = agentRunId;
-                    this.queueStepSave(stepEntity);
+                    // Re-apply post-INSERT: this callback can fire while the step's INSERT is still in flight,
+                    // and the INSERT's reload would otherwise revert TargetLogID back to null.
+                    this.queueStepSave(stepEntity, (s) => { s.TargetLogID = agentRunId; });
                 }
             });
             // Check if execution was successful
@@ -4604,6 +5469,11 @@ The context is now within limits. Please retry your request with the recovered c
         if (params.data?.conversationId) {
             this._agentRun.ConversationID = params.data.conversationId;
         }
+        // Stamp the realtime/long-lived session id (if any) so every run — including delegated
+        // child runs that inherit this value — is groupable under the same MJ: AI Agent Session.
+        if (params.agentSessionID) {
+            this._agentRun.AgentSessionID = params.agentSessionID;
+        }
         this._agentRun.Status = 'Running';
         this._agentRun.StartedAt = new Date();
         this._agentRun.UserID = params.userId || params.contextUser?.ID || null;
@@ -4761,38 +5631,42 @@ The context is now within limits. Please retry your request with the recovered c
      */
     async createStepEntity(params) {
         const stepEntity = await this._activeProvider.GetEntityObject('MJ: AI Agent Run Steps', params.contextUser);
-        stepEntity.AgentRunID = this._agentRun.ID;
+        // Client-generate the PK so the step ID is valid IMMEDIATELY (before the INSERT lands) — child
+        // steps link via ParentID and the post-create UPDATE-phase mutations reference this row, and the
+        // create INSERT is fire-and-forget (the agent flow must not block on it).
+        stepEntity.NewRecord();
         // Step number is based on current count of steps + 1
-        stepEntity.StepNumber = (this._agentRun.Steps?.length || 0) + 1;
-        stepEntity.StepType = params.stepType;
-        // Include hierarchy breadcrumb in StepName for better logging
-        stepEntity.StepName = this.formatHierarchicalMessage(params.stepName);
-        // check to see if targetId is a valid UUID
+        const stepNumber = (this._agentRun.Steps?.length || 0) + 1;
+        // Warn on a non-UUID targetId before delegating (initAgentRunStep silently ignores invalid ids).
         if (params.targetId && !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(params.targetId)) {
-            // If not valid, we can just ignore it, but console.warn
             console.warn(`Invalid target ID format: ${params.targetId}`);
         }
-        else {
-            stepEntity.TargetID = params.targetId || null;
-        }
-        stepEntity.TargetLogID = params.targetLogId || null;
-        stepEntity.ParentID = params.parentId || null; // Link to parent step (e.g., loop step)
-        stepEntity.Status = 'Running';
-        stepEntity.StartedAt = new Date();
-        stepEntity.PayloadAtStart = this.serializePayloadAtStart(params.payloadAtStart);
-        stepEntity.PayloadAtEnd = this.serializePayloadAtEnd(params.payloadAtEnd);
-        // Populate InputData if provided
-        if (params.inputData) {
-            stepEntity.InputData = JSON.stringify({
-                ...params.inputData,
-                context: {
-                    agentHierarchy: this._agentHierarchy,
-                    depth: this._depth,
-                    stepNumber: stepEntity.StepNumber
-                }
-            });
-        }
-        this.queueStepSave(stepEntity);
+        // Populate the started fields via the shared single-source-of-truth helper. Instance-specific
+        // concerns (hierarchy breadcrumb, InputData context, payload serialization) are computed here.
+        initAgentRunStep(stepEntity, {
+            AgentRunID: this._agentRun.ID,
+            StepNumber: stepNumber,
+            StepType: params.stepType,
+            StepName: this.formatHierarchicalMessage(params.stepName), // include hierarchy breadcrumb
+            TargetID: params.targetId,
+            TargetLogID: params.targetLogId,
+            ParentID: params.parentId, // Link to parent step (e.g., loop step)
+            PayloadAtStart: this.serializePayloadAtStart(params.payloadAtStart),
+            PayloadAtEnd: this.serializePayloadAtEnd(params.payloadAtEnd),
+            InputData: params.inputData
+                ? JSON.stringify({
+                    ...params.inputData,
+                    context: {
+                        agentHierarchy: this._agentHierarchy,
+                        depth: this._depth,
+                        stepNumber
+                    }
+                })
+                : undefined
+        });
+        // Fire-and-forget the 'started' INSERT — the agent flow never blocks on a step save. The queue
+        // tracks the INSERT so every later UPDATE (queueStepSave) chains AFTER it commits.
+        this._stepSaveQueue.Insert(stepEntity);
         // Add the step to the agent run's Steps array
         if (this._agentRun) {
             this._agentRun.Steps.push(stepEntity);
@@ -4859,57 +5733,42 @@ The context is now within limits. Please retry your request with the recovered c
      */
     async finalizeStepEntity(stepEntity, success, errorMessage, outputData) {
         try {
-            stepEntity.Status = success ? 'Completed' : 'Failed';
-            stepEntity.CompletedAt = new Date();
-            stepEntity.Success = success;
-            stepEntity.ErrorMessage = errorMessage || null;
-            // Populate OutputData if provided
-            if (outputData) {
-                stepEntity.OutputData = JSON.stringify({
-                    ...CopyScalarsAndArrays(outputData, true),
-                    context: {
-                        success,
-                        durationMs: stepEntity.CompletedAt.getTime() - stepEntity.StartedAt.getTime(),
-                        errorMessage
-                    }
-                });
-            }
-            this.queueStepSave(stepEntity);
+            // Capture the completion timestamp NOW so the duration is accurate regardless of when the
+            // mutation is actually applied/persisted.
+            const finalizeOpts = {
+                success,
+                errorMessage,
+                outputData: outputData ? CopyScalarsAndArrays(outputData, true) : undefined,
+                completedAt: new Date(),
+                // Capture any TargetLogID already stamped on the entity (e.g. a prompt-run / sub-agent-run id
+                // set before finalize) so the post-INSERT re-apply restores it too — otherwise the INSERT's
+                // reload could leave it null on a fast step.
+                targetLogID: stepEntity.TargetLogID ?? undefined
+            };
+            // Apply to the in-memory entity NOW so the run's Steps array / UI see the terminal state
+            // immediately. This in-memory copy can be reverted by the INSERT's post-save reload if the step
+            // finished while its INSERT was still in flight, which is why we ALSO re-apply it inside the
+            // post-INSERT continuation below (idempotent — same completedAt).
+            finalizeAgentRunStep(stepEntity, finalizeOpts);
+            // Fire-and-forget the UPDATE, but re-assert the finalize state AFTER the INSERT (and its reload)
+            // lands so the force-persisted UPDATE never writes stale pre-finalize values. The agent flow
+            // never blocks on this UPDATE.
+            this.queueStepSave(stepEntity, (s) => finalizeAgentRunStep(s, finalizeOpts));
         }
         catch (e) {
             LogError(`Failed to update agent run step record: ${e?.message ?? e}`, undefined, e);
         }
     }
     /**
-     * Queues a database save for a step entity.
-     *
-     * - Saves on the same step record are chained (sequenced) to prevent an UPDATE
-     *   from racing the original INSERT.
-     * - Saves on different step records run concurrently.
-     * - Failures are not thrown — they're logged via `LogError` (with the entity's
-     *   `LatestResult.CompleteMessage` per the BaseEntity convention) so the
-     *   agent loop isn't blocked by observability writes — but they ARE surfaced
-     *   in `finalizeAgentRun` so callers see step-record drift.
-     *
-     * Exposed as `protected` so driver sub-classes (e.g. Skip) that author
-     * custom `AIAgentRunStep` records can fire-and-forget saves through the
-     * same chained/non-blocking machinery instead of awaiting `entity.Save()`
-     * inline and blocking the agent loop.
+     * Queues a fire-and-forget UPDATE of a step entity whose fields the caller has ALREADY mutated.
+     * Delegates to {@link AgentRunStepSaveQueue.QueueUpdate} — the agent flow never awaits this; the UPDATE
+     * chains after the step's INSERT and force-persists (`IgnoreDirtyState`). Kept `protected` so driver
+     * subclasses that finalize their own steps get the same non-blocking behavior.
      *
      * @protected
      */
-    queueStepSave(stepEntity) {
-        // Chain on the entity INSTANCE (stable), NOT stepEntity.ID — the ID is empty until the INSERT
-        // Save() assigns it, so an ID-keyed chain breaks for fast create→finalize sequences.
-        const previousSave = this._stepSavePromises.get(stepEntity) ?? Promise.resolve();
-        const currentSave = previousSave.then(() => stepEntity.Save()).then((ok) => {
-            if (!ok) {
-                LogError(`Failed to save agent run step record ${stepEntity.ID || '(unsaved)'}: ${stepEntity.LatestResult?.CompleteMessage ?? 'unknown error'}`);
-            }
-            return ok;
-        });
-        this._stepSavePromises.set(stepEntity, currentSave);
-        this._pendingSaves.push(currentSave);
+    queueStepSave(stepEntity, applyMutation) {
+        this._stepSaveQueue.QueueUpdate(stepEntity, applyMutation);
     }
     /**
      * Maps an array through an async worker with bounded concurrency.
@@ -5242,10 +6101,8 @@ The context is now within limits. Please retry your request with the recovered c
                 },
                 displayMode: 'live' // Only show in live mode
             });
-            // Set PayloadAtStart
-            if (stepEntity && payload) {
-                stepEntity.PayloadAtStart = this.serializePayloadAtStart(payload);
-            }
+            // PayloadAtStart was already serialized from this same `payload` by createStepEntity
+            // above (payloadAtStart: payload) — no need to re-serialize the (potentially large) payload here.
             let downstreamPayload = payload; // Start with current payload
             if (params.agent.PayloadSelfReadPaths) {
                 const downstreamPaths = JSON.parse(params.agent.PayloadSelfReadPaths);
@@ -5282,7 +6139,9 @@ The context is now within limits. Please retry your request with the recovered c
             } : undefined;
             promptParams.onPromptRunCreated = async (promptRunId) => {
                 stepEntity.TargetLogID = promptRunId;
-                this.queueStepSave(stepEntity);
+                // Re-apply post-INSERT: onPromptRunCreated can fire before the step's INSERT lands, and the
+                // INSERT's reload would otherwise revert TargetLogID back to null.
+                this.queueStepSave(stepEntity, (s) => { s.TargetLogID = promptRunId; });
             };
             // Execute the prompt
             const promptResult = await this.executePrompt(promptParams);
@@ -5294,7 +6153,7 @@ The context is now within limits. Please retry your request with the recovered c
             // Update step entity with AIPromptRun ID if available
             if (promptResult.promptRun?.ID) {
                 stepEntity.TargetLogID = promptResult.promptRun.ID;
-                stepEntity.PromptRun = promptResult.promptRun; // Store the prompt run object
+                stepEntity.PromptRun = promptResult.promptRun; // transient related object (not a persisted field)
                 // don't save here, we save when we call finalizeStepEntity()
             }
             // Check if prompt execution failed
@@ -5411,6 +6270,11 @@ The context is now within limits. Please retry your request with the recovered c
             else if (this._artifactToolManager.HasArtifacts()) {
                 this.logStatus(`[ArtifactTools] LLM did not use artifact tools this turn (artifacts available but not accessed)`, true, params);
             }
+            // Execute in-flight memory writes if provided (zero turn cost — processed inline)
+            const memoryWrites = initialNextStep.memoryWrites;
+            if (memoryWrites?.length) {
+                await this.processMemoryWritesForTurn(memoryWrites, params);
+            }
             // Execute a tool pipeline if provided (zero turn cost — processed inline). Each step's
             // output is threaded into the next server-side; only the final step's output returns to
             // the LLM, so intermediate payloads never enter the context window.
@@ -5797,7 +6661,7 @@ The context is now within limits. Please retry your request with the recovered c
             // Update step entity with AIAgentRun ID if available
             if (subAgentResult.agentRun?.ID) {
                 stepEntity.TargetLogID = subAgentResult.agentRun.ID;
-                // Set the SubAgentRun property for hierarchical tracking
+                // Set the SubAgentRun property for hierarchical tracking (transient related object)
                 stepEntity.SubAgentRun = subAgentResult.agentRun;
                 stepEntity.PayloadAtEnd = this.serializePayloadAtEnd(mergedPayload);
                 // saving happens later by calling finalizeStepEntity()
@@ -6926,8 +7790,11 @@ The context is now within limits. Please retry your request with the recovered c
                     actionResult = await this.ExecuteSingleAction(params, aa, actionEntity, params.contextUser);
                     // Update step entity with ActionExecutionLog ID if available
                     if (actionResult.LogEntry?.ID) {
-                        stepEntity.TargetLogID = actionResult.LogEntry.ID;
-                        this.queueStepSave(stepEntity);
+                        const logId = actionResult.LogEntry.ID;
+                        stepEntity.TargetLogID = logId;
+                        // Re-apply post-INSERT: a fast action can finish before the step's INSERT lands, and
+                        // the INSERT's reload would otherwise revert TargetLogID back to null.
+                        this.queueStepSave(stepEntity, (s) => { s.TargetLogID = logId; });
                     }
                     // Prepare output data with action result
                     const outputData = {
@@ -8203,27 +9070,15 @@ The context is now within limits. Please retry your request with the recovered c
      * @private
      */
     async finalizeAgentRun(finalStep, payload, contextUser) {
-        // Await every pending step save (success OR failure) and accumulate diagnostics.
-        // We use allSettled so a single failure doesn't shadow the rest, and we drain
-        // both queues afterwards so an instance reused for another run doesn't leak
-        // settled promises.
-        const pending = this._pendingSaves;
-        this._pendingSaves = [];
-        this._stepSavePromises.clear();
-        if (pending.length > 0) {
-            const settled = await Promise.allSettled(pending);
-            const rejections = settled.filter(s => s.status === 'rejected');
-            const falses = settled.filter(s => s.status === 'fulfilled' && s.value === false).length;
-            for (const r of rejections) {
-                LogError(`Pending step save rejected: ${r.reason instanceof Error ? r.reason.message : String(r.reason)}`);
-            }
-            const totalFailures = rejections.length + falses;
-            if (totalFailures > 0 && this._agentRun) {
-                const note = `${totalFailures} step record save(s) failed during this run; see logs for details.`;
-                this._agentRun.ErrorMessage = this._agentRun.ErrorMessage
-                    ? `${this._agentRun.ErrorMessage}\n${note}`
-                    : note;
-            }
+        // Flush every pending step save (success OR failure) via the shared queue, which allSettles so a
+        // single failure doesn't shadow the rest and drains itself so a reused instance doesn't leak
+        // settled promises. Surface the failure count on the run for visibility.
+        const { failures } = await this._stepSaveQueue.Flush();
+        if (failures > 0 && this._agentRun) {
+            const note = `${failures} step record save(s) failed during this run; see logs for details.`;
+            this._agentRun.ErrorMessage = this._agentRun.ErrorMessage
+                ? `${this._agentRun.ErrorMessage}\n${note}`
+                : note;
         }
         // Only resolve media placeholders for ROOT agents (depth === 0)
         // Sub-agents keep placeholders intact so parent agents don't get huge base64 in their context
@@ -8259,12 +9114,17 @@ The context is now within limits. Please retry your request with the recovered c
             else {
                 this._agentRun.Status = 'Completed';
             }
-            this._agentRun.Result = resolvedPayload ? JSON.stringify(resolvedPayload) : null;
+            // Serialize the (largest-it-ever-gets) final payload ONCE and reuse for both
+            // Result and FinalPayload instead of stringifying the same object three times.
+            const finalPayloadJson = resolvedPayload ? JSON.stringify(resolvedPayload) : null;
+            this._agentRun.Result = finalPayloadJson;
             this._agentRun.FinalStep = finalStep.step;
             this._agentRun.Message = finalStep.message;
-            // Set the FinalPayloadObject - this will automatically stringify for the DB
+            // Set the FinalPayloadObject (populates the object cache; its setter also writes
+            // FinalPayload when the value changes). We then assign FinalPayload from the
+            // already-computed JSON to guarantee it's set regardless of the setter's change guard.
             this._agentRun.FinalPayloadObject = resolvedPayload;
-            this._agentRun.FinalPayload = resolvedPayload ? JSON.stringify(resolvedPayload) : null;
+            this._agentRun.FinalPayload = finalPayloadJson;
             // Calculate total tokens from all prompts and sub-agents
             const tokenStats = this.calculateTokenStats();
             this._agentRun.TotalTokensUsed = tokenStats.totalTokens;