@memberjunction/ai-agents 5.40.2 → 5.41.0

package/dist/agent-types/realtime-agent-type.js

@@ -0,0 +1,176 @@
+/**
+ * @fileoverview Implementation of the Realtime Agent Type for streaming, full-duplex,
+ * tool-calling sessions (voice today, video later).
+ *
+ * Unlike {@link LoopAgentType} and `FlowAgentType`, the Realtime agent type does **not**
+ * drive an iterative request/response reasoning loop. Modern real-time models (Gemini Live,
+ * GPT Realtime, and — as a fast-follow — the Eleven Labs stack) own the listen-reason-speak
+ * loop themselves. The Realtime agent type therefore wraps a `BaseRealtimeModel` session and
+ * delegates the conversation lifecycle to {@link RealtimeSessionRunner}, instead of being
+ * pumped turn-by-turn by `BaseAgent`'s loop.
+ *
+ * This class is built in isolation (P2b-i): it is a registered peer of Loop/Flow, but the
+ * wiring inside `BaseAgent` that branches into the session runner is a separate later task.
+ * The {@link RealtimeAgentType.IsSessionDriven} getter is the marker `BaseAgent` will use to
+ * make that branch.
+ *
+ * @module @memberjunction/ai-agents
+ * @author MemberJunction.com
+ */
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { RegisterClass } from '@memberjunction/global';
+import { LogError } from '@memberjunction/core';
+import { BaseAgentType } from './base-agent-type.js';
+/**
+ * Implementation of the Realtime Agent Type pattern.
+ *
+ * A first-class peer of Loop and Flow that drives a {@link BaseRealtimeModel} session rather
+ * than an iterative reasoning loop. Because it is a real MJ agent type, an agent of this type
+ * inherits the entire framework for free: server tools (actions), client tools, artifacts,
+ * prompts, memory, permissions, and observability. The first agent shipped of this type is the
+ * Realtime Co-Agent, which voices on behalf of a target agent.
+ *
+ * **Execution branch.** The realtime path is session-driven: `BaseAgent` (in a later task) will
+ * detect {@link IsSessionDriven} (or `instanceof RealtimeAgentType`) and hand control to a
+ * {@link RealtimeSessionRunner} rather than entering the loop. As a consequence, the
+ * loop-oriented abstract methods below are implemented defensively — they should never be reached
+ * in normal operation.
+ *
+ * @class RealtimeAgentType
+ * @extends BaseAgentType
+ */
+let RealtimeAgentType = class RealtimeAgentType extends BaseAgentType {
+    /**
+     * Marks this agent type as session-driven rather than loop-driven.
+     *
+     * `BaseAgent` will use this getter (added on this subclass; `base-agent-type.ts` is left
+     * untouched in this task) to branch into a {@link RealtimeSessionRunner} instead of the
+     * iterative reasoning loop. Other agent types do not expose this member; `BaseAgent` should
+     * treat its absence as `false`, or equivalently detect this type via `instanceof
+     * RealtimeAgentType`.
+     *
+     * @returns Always `true` — realtime agents are driven by a long-lived duplex session.
+     */
+    get IsSessionDriven() {
+        return true;
+    }
+    /**
+     * Realtime agents drive their conversation through a live model session, not through
+     * agent-level loop prompts. The companion/system prompt is supplied to the realtime model at
+     * session start, so the agent-level prompt relationship is not required.
+     *
+     * @returns Always `false` — agent-level loop prompts are not required for realtime agents.
+     */
+    get RequiresAgentLevelPrompts() {
+        return false;
+    }
+    /**
+     * Initializes agent-type-specific state for a realtime run.
+     *
+     * The Realtime agent type keeps no iterative loop state — all live state lives inside the
+     * {@link RealtimeSessionRunner} and the underlying provider session — so an empty state object
+     * is returned, mirroring {@link LoopAgentType.InitializeAgentTypeState}.
+     *
+     * @param params The agent execution params (unused for realtime state).
+     * @returns An empty agent-type state object.
+     */
+    async InitializeAgentTypeState(params) {
+        // Realtime agents do not maintain iterative loop state; the session runner + provider
+        // session own all live state. Return an empty object to satisfy the contract.
+        return {};
+    }
+    /**
+     * Determines the next step from a prompt result.
+     *
+     * Realtime agents are session-driven and never enter the iterative reasoning loop, so this
+     * method should never be reached in normal operation. It is implemented defensively: it logs
+     * and returns a terminal `Failed` step rather than throwing, so a mis-wired caller degrades
+     * gracefully instead of crashing a live session.
+     *
+     * @param promptResult Result from prompt execution (unused).
+     * @param params The full execution parameters (unused).
+     * @param payload The current payload (unused).
+     * @param agentTypeState The agent-type state (unused).
+     * @returns A terminal `Failed` step describing the misuse.
+     */
+    async DetermineNextStep(promptResult, params, payload, agentTypeState) {
+        const message = 'RealtimeAgentType.DetermineNextStep was called, but realtime agents are session-driven and ' +
+            'do not use the iterative reasoning loop. This indicates the agent was routed through the loop ' +
+            'path instead of the RealtimeSessionRunner. Check that BaseAgent branched on IsSessionDriven.';
+        LogError(message);
+        return this.createNextStep('Failed', { terminate: true, errorMessage: message });
+    }
+    /**
+     * Determines the initial step for a realtime agent.
+     *
+     * The realtime conversation is owned by the session runner, so there is no loop step to
+     * begin. Returning `null` defers to the caller; in practice `BaseAgent` branches on
+     * {@link IsSessionDriven} before this would matter.
+     *
+     * @param params The full execution parameters (unused).
+     * @param payload The current payload (unused).
+     * @param agentTypeState The agent-type state (unused).
+     * @returns Always `null` — there is no loop step to seed.
+     */
+    async DetermineInitialStep(params, payload, agentTypeState) {
+        return null;
+    }
+    /**
+     * Pre-processes a retry step.
+     *
+     * Realtime agents have no loop retry semantics; `null` is returned to indicate "no custom
+     * behavior", consistent with {@link LoopAgentType.PreProcessNextStep}.
+     *
+     * @param params The full execution parameters (unused).
+     * @param step The retry step (unused).
+     * @param payload The current payload (unused).
+     * @param agentTypeState The agent-type state (unused).
+     * @returns Always `null`.
+     */
+    async PreProcessNextStep(params, step, payload, agentTypeState) {
+        return null;
+    }
+    /**
+     * Gets the prompt to use for a step.
+     *
+     * Realtime agents do not select per-step loop prompts — the companion/system prompt is handed
+     * to the realtime model at session start. The default child prompt (if any) is returned for
+     * completeness, but it is not used to drive the conversation.
+     *
+     * @param params The execution parameters (unused).
+     * @param config The loaded agent configuration.
+     * @param payload The current payload (unused).
+     * @param agentTypeState The agent-type state (unused).
+     * @param previousDecision The previous step decision (unused).
+     * @returns The configured child prompt, or `null` if none is configured.
+     */
+    async GetPromptForStep(params, config, payload, agentTypeState, previousDecision) {
+        return config.childPrompt || null;
+    }
+    /**
+     * Injects a payload into a prompt.
+     *
+     * Realtime conversations are not driven by loop prompts, so there is no per-turn payload to
+     * inject. This is a no-op (defensive against a mis-wired caller), in contrast to
+     * {@link LoopAgentType.InjectPayload} which injects the current payload into the loop prompt.
+     *
+     * @param payload The payload to inject (unused).
+     * @param agentTypeState The agent-type state (unused).
+     * @param prompt The prompt parameters (unused).
+     * @param agentInfo Agent identification info (unused).
+     */
+    async InjectPayload(payload, agentTypeState, prompt, agentInfo) {
+        // No-op: the realtime session runner owns context injection at session start, not the
+        // per-turn loop prompt path. Nothing to inject here.
+    }
+};
+RealtimeAgentType = __decorate([
+    RegisterClass(BaseAgentType, "RealtimeAgentType")
+], RealtimeAgentType);
+export { RealtimeAgentType };
+//# sourceMappingURL=realtime-agent-type.js.map

package/dist/agent-types/realtime-agent-type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"realtime-agent-type.js","sourceRoot":"","sources":["../../src/agent-types/realtime-agent-type.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;;;;;;;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAShD,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAElD;;;;;;;;;;;;;;;;;GAiBG;AAEI,IAAM,iBAAiB,GAAvB,MAAM,iBAAkB,SAAQ,aAAa;IAChD;;;;;;;;;;OAUG;IACH,IAAW,eAAe;QACtB,OAAO,IAAI,CAAC;IAChB,CAAC;IAED;;;;;;OAMG;IACH,IAAoB,yBAAyB;QACzC,OAAO,KAAK,CAAC;IACjB,CAAC;IAED;;;;;;;;;OASG;IACI,KAAK,CAAC,wBAAwB,CAAqB,MAAkC;QACxF,sFAAsF;QACtF,8EAA8E;QAC9E,OAAO,EAAS,CAAC;IACrB,CAAC;IAED;;;;;;;;;;;;;OAaG;IACI,KAAK,CAAC,iBAAiB,CAC1B,YAAsC,EACtC,MAAkC,EAClC,OAAU,EACV,cAAmB;QAEnB,MAAM,OAAO,GACT,6FAA6F;YAC7F,gGAAgG;YAChG,8FAA8F,CAAC;QACnG,QAAQ,CAAC,OAAO,CAAC,CAAC;QAClB,OAAO,IAAI,CAAC,cAAc,CAAI,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,CAAC,CAAC;IACxF,CAAC;IAED;;;;;;;;;;;OAWG;IACI,KAAK,CAAC,oBAAoB,CAC7B,MAA6B,EAC7B,OAAU,EACV,cAAmB;QAEnB,OAAO,IAAI,CAAC;IAChB,CAAC;IAED;;;;;;;;;;;OAWG;IACI,KAAK,CAAC,kBAAkB,CAC3B,MAA6B,EAC7B,IAA0B,EAC1B,OAAU,EACV,cAAmB;QAEnB,OAAO,IAAI,CAAC;IAChB,CAAC;IAED;;;;;;;;;;;;;OAaG;IACI,KAAK,CAAC,gBAAgB,CACzB,MAA0B,EAC1B,MAA0B,EAC1B,OAAU,EACV,cAAmB,EACnB,gBAA8C;QAE9C,OAAO,MAAM,CAAC,WAAW,IAAI,IAAI,CAAC;IACtC,CAAC;IAED;;;;;;;;;;;OAWG;IACI,KAAK,CAAC,aAAa,CACtB,OAAU,EACV,cAAmB,EACnB,MAAsB,EACtB,SAAmD;QAEnD,sFAAsF;QACtF,qDAAqD;IACzD,CAAC;CACJ,CAAA;AA7JY,iBAAiB;IAD7B,aAAa,CAAC,aAAa,EAAE,mBAAmB,CAAC;GACrC,iBAAiB,CA6J7B"}

package/dist/base-agent.d.ts

@@ -11,15 +11,40 @@
  * @since 2.49.0
  */
 import { MJAIAgentTypeEntity, MJTemplateParamEntity, MJAIAgentRelationshipEntity, MJAIAgentNoteEntity, MJAIAgentExampleEntity } from '@memberjunction/core-entities';
-import { MJAIAgentRunEntityExtended, MJAIAgentRunStepEntityExtended, MJAIPromptEntityExtended, MJAIAgentEntityExtended } from "@memberjunction/ai-core-plus";
+import { MJAIAgentRunEntityExtended, MJAIAgentRunStepEntityExtended, MJAIPromptEntityExtended, MJAIAgentEntityExtended, MJAIPromptRunEntityExtended } from "@memberjunction/ai-core-plus";
 import { UserInfo, IMetadataProvider } from '@memberjunction/core';
-import { ChatMessage, ChatMessageContent } from '@memberjunction/ai';
+import { ChatMessage, ChatMessageContent, BaseRealtimeModel } from '@memberjunction/ai';
 import { BaseAgentType } from './agent-types/base-agent-type.js';
+import { RealtimeSessionRunnerDeps } from './realtime/realtime-session-runner.js';
+import { RealtimeCoAgentConfig } from './realtime/realtime-coagent-config.js';
+import { AIEngine } from '@memberjunction/aiengine';
 import { AgentPreExecutionRAGResult } from './agent-pre-execution-rag.js';
-import { AIPromptParams, AIPromptRunResult, ExecuteAgentParams, AgentConfiguration, ExecuteAgentResult, AgentAction, AgentSubAgentRequest, BaseAgentNextStep, MessageLifecycleEvent, AgentChatMessage, AIModelSelectionInfo, ActionChange, ActionChangeScope, MediaOutput, FileOutputRef, SecondaryScopeConfig, SecondaryScopeValue, AgentPipelineRequest } from '@memberjunction/ai-core-plus';
+import { AIPromptParams, AIPromptRunResult, ExecuteAgentParams, AgentConfiguration, ExecuteAgentResult, AgentAction, AgentSubAgentRequest, BaseAgentNextStep, MessageLifecycleEvent, AgentChatMessage, AIModelSelectionInfo, ActionChange, ActionChangeScope, SubAgentChange, MediaOutput, FileOutputRef, SecondaryScopeConfig, SecondaryScopeValue, AgentPipelineRequest } from '@memberjunction/ai-core-plus';
 import { MJActionEntityExtended, ActionResult } from '@memberjunction/actions-base';
 import { ArtifactToolCall, StoredToolResult } from './ArtifactToolManager.js';
+import { MemoryWriteRequest, MemoryWriteResult } from './MemoryWriteManager.js';
 import { PipelineToolRegistry, PipelineExecutionResult } from './pipeline/index.js';
+/**
+ * The agent-invariant "base" catalog cached (process-wide) on AIEngine and reused across runs/steps.
+ * Holds the resolved sub-agents + actions and their formatted markdown, plus the base merged
+ * agent-type prompt params (with NO runtime overrides applied). Runtime `actionChanges` /
+ * `subAgentChanges` / `__agentTypePromptParams` overrides are layered on top per run from a clone.
+ */
+interface AgentBaseCatalog {
+    /** Resolved active sub-agents (direct ParentID children + active relationships), de-duped. */
+    uniqueActiveSubAgents: MJAIAgentEntityExtended[];
+    subAgentCount: number;
+    /** Markdown describing uniqueActiveSubAgents (the base set). */
+    subAgentDetails: string;
+    /** Actions matched to the agent's active AIAgentAction junctions, BEFORE filtering by action Status — needed as the input to applyActionChanges. */
+    baseActionsRaw: MJActionEntityExtended[];
+    /** baseActionsRaw filtered to Status='Active' — the fast-path effective action set. */
+    activeActions: MJActionEntityExtended[];
+    /** Markdown describing activeActions (the base set). */
+    actionDetails: string;
+    /** Agent-type prompt params merged from schema defaults + agent config (NO runtime overrides). */
+    baseAgentTypePromptParams: Record<string, unknown>;
+}
 export declare class BaseAgent {
     /**
      * Maximum allowed validation retries before forcing failure.
@@ -69,6 +94,16 @@ export declare class BaseAgent {
      * INSERT on millisecond-fast steps (e.g. pipelines), which left them stuck at `Running`.
      */
     private _stepSavePromises;
+    /**
+     * Per-step 'started'-INSERT promises, keyed by the step entity instance. The create INSERT is
+     * fire-and-forget (the agent flow never blocks on it — the PK is client-generated by NewRecord() so
+     * the ID is valid immediately). Every UPDATE-phase save ({@link queueStepSave}) chains after this
+     * INSERT promise so the UPDATE never races ahead of the create, and force-persists with
+     * `IgnoreDirtyState` so a mutation absorbed by the INSERT's post-save dirty-reset (which silently
+     * no-op'd UPDATEs and left fast create→finalize steps stuck at Status='Running') is still written.
+     * A WeakMap so entries are GC'd with the entity.
+     */
+    private _stepInsertPromises;
     /**
      * Active per-request metadata provider, set at the start of Execute().
      * Defaults to the global Metadata.Provider; overridden when a per-request
@@ -358,6 +393,11 @@ export declare class BaseAgent {
      * Allows agents to explore input artifacts on demand.
      */
     private _artifactToolManager;
+    /**
+     * Manages in-flight durable memory writes for the current agent run.
+     * Only consulted when the agent has AllowMemoryWrite enabled.
+     */
+    private _memoryWriteManager;
     /**
      * Effective actions available to this agent after applying actionChanges.
      * Populated during gatherPromptTemplateData() and used for validation in executeActionsStep().
@@ -490,6 +530,247 @@ export declare class BaseAgent {
      */
     protected get DefaultAgentTimeoutMS(): number;
     Execute<C = any, R = any>(params: ExecuteAgentParams<C>): Promise<ExecuteAgentResult<R>>;
+    /**
+     * 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.
+     */
+    protected isSessionDrivenAgentType(agentType: BaseAgentType): agentType is BaseAgentType & {
+        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}.
+     */
+    protected executeRealtimeSession<R = any>(params: ExecuteAgentParams, config: AgentConfiguration): Promise<ExecuteAgentResult<R>>;
+    /**
+     * 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`.
+     */
+    protected resolveRealtimeModel(params: ExecuteAgentParams): Promise<{
+        model: BaseRealtimeModel;
+        modelID: string;
+        vendorID: string;
+        apiName: string;
+        driverClass?: string;
+    } | null>;
+    /**
+     * Selects the `MJ: AI Models` row to use for a realtime session: the highest-power active
+     * model of AIModelType `Realtime`. Returns `null` when no `Realtime` model exists in metadata
+     * (expected before P4).
+     *
+     * @param agent The agent being executed (reserved for future per-agent model preference).
+     * @returns The chosen model entity, or `null`.
+     */
+    private selectRealtimeModelEntity;
+    /**
+     * 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`).
+     */
+    protected resolveRealtimeEffectiveConfig(agent: MJAIAgentEntityExtended): RealtimeCoAgentConfig;
+    /**
+     * 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.
+     */
+    private selectRealtimeVendor;
+    /**
+     * 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.
+     */
+    private createRealtimePromptRun;
+    /**
+     * 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.
+     */
+    protected buildRealtimeSessionDeps(params: ExecuteAgentParams, config: AgentConfiguration, modelResolution: {
+        model: BaseRealtimeModel;
+        apiName: string;
+        driverClass?: string;
+    }, promptRun: MJAIPromptRunEntityExtended | null): Promise<RealtimeSessionRunnerDeps>;
+    /**
+     * 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.
+     */
+    private buildRealtimeSessionParams;
+    /**
+     * 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).
+     */
+    private assembleRealtimeContext;
+    /**
+     * 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.
+     */
+    private delegateRealtimeToTarget;
+    /**
+     * 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.
+     */
+    private combineProgressCallbacks;
+    /**
+     * 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`.
+     */
+    private resolveRealtimeTargetAgent;
+    /**
+     * 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.
+     */
+    private parseDelegateRequestText;
+    /**
+     * 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.
+     */
+    private executeRealtimeTool;
+    /**
+     * 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).
+     */
+    private parseRealtimeToolParams;
+    /**
+     * 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.
+     */
+    private persistRealtimeTranscript;
+    /**
+     * 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.
+     */
+    private checkpointRealtimeUsage;
+    /**
+     * 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.
+     */
+    private finalizeRealtimeRun;
+    /**
+     * 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.
+     */
+    private createSessionSuccessStep;
     /**
      * Sub-classes can override this method to perform any specialized initialization
      * @param params
@@ -526,21 +807,16 @@ export declare class BaseAgent {
      * @protected
      */
     protected initializeEngines(contextUser?: UserInfo): Promise<void>;
-    /**
-     * Storage for injected memory context to prepend to prompts
-     */
-    private _memoryContext;
     /**
      * Storage for injected notes and examples to include in result
      */
     private _injectedMemory;
     /**
      * 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}.
      */
-    private _ragContext;
     private _injectedRAG;
     /**
      * Determine the scope label for a note based on its scope fields.
@@ -998,6 +1274,42 @@ export declare class BaseAgent {
      * @protected
      */
     protected capStandaloneToolResultText(text: string): string;
+    /**
+     * 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
+     */
+    protected executeMemoryWritesAsSteps(writes: MemoryWriteRequest[], params: ExecuteAgentParams): Promise<MemoryWriteResult[]>;
+    /**
+     * 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
+     */
+    protected processMemoryWritesForTurn(memoryWrites: MemoryWriteRequest[], params: ExecuteAgentParams): Promise<void>;
+    /**
+     * 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
+     */
+    protected injectMemoryWriteResultsMessage(params: ExecuteAgentParams, results: MemoryWriteResult[]): void;
     /**
      * 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
@@ -1055,6 +1367,28 @@ export declare class BaseAgent {
      * @private
      */
     private gatherPromptTemplateData;
+    /**
+     * 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
+     */
+    protected buildAgentBaseCatalog(agent: MJAIAgentEntityExtended, engine: AIEngine): AgentBaseCatalog;
+    /**
+     * 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
+     */
+    protected applySubAgentChanges(baseSubAgents: MJAIAgentEntityExtended[], subAgentChanges: SubAgentChange[], agentId: string, isRoot: boolean, engine: AIEngine): MJAIAgentEntityExtended[];
+    /**
+     * Filters/transforms sub-agent changes for propagation to a sub-agent — the sub-agent counterpart
+     * of {@link filterActionChangesForSubAgent} (same propagation rules).
+     *
+     * @protected
+     */
+    protected filterSubAgentChangesForSubAgent(subAgentChanges: SubAgentChange[] | undefined): SubAgentChange[] | undefined;
     /**
      * Builds merged agent type prompt params from schema defaults,
      * agent config, and runtime overrides.
@@ -1408,20 +1742,26 @@ export declare class BaseAgent {
      */
     protected finalizeStepEntity(stepEntity: MJAIAgentRunStepEntityExtended, success: boolean, errorMessage?: string, outputData?: any): Promise<void>;
     /**
-     * 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.
+     * Saves one step record and ALWAYS logs (never swallows, never verbose-gated) a failure via `LogError`
+     * with `LatestResult.CompleteMessage` — the log is observability, so a failure must surface but must
+     * not throw into the agent loop. The `update` phase force-saves with `IgnoreDirtyState` because a
+     * finalize/TargetLogID mutation applied while the INSERT was still in flight gets absorbed by the
+     * INSERT's post-save dirty-reset, leaving the new values only in memory (the "step stuck at Running"
+     * bug); forcing the UPDATE re-persists them. `insert` saves normally.
+     * @returns whether the row persisted.
+     */
+    private saveStepRecord;
+    /**
+     * Queues a fire-and-forget UPDATE of a step entity whose fields the caller has ALREADY mutated.
      *
-     * 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.
+     * - The agent flow never awaits this (logging is fire-and-forget).
+     * - Chains after the step's 'started' INSERT and any prior queued save, so the UPDATE never races
+     *   ahead of the INSERT; updates to DIFFERENT steps run concurrently.
+     * - Force-persists (IgnoreDirtyState) because a mutation applied while the INSERT was in flight can be
+     *   absorbed by the INSERT's post-save dirty-reset, leaving the entity "clean" with the new values
+     *   only in memory — without the force, the UPDATE would silently no-op and the row would stay stuck
+     *   at Status='Running' / null TargetLogID.
+     * - Failures are logged (never thrown) and surfaced via `_pendingSaves` at run finalize.
      *
      * @protected
      */
@@ -2199,4 +2539,5 @@ export declare class BaseAgent {
      */
     private validateAndApplySecondaryScopes;
 }
+export {};
 //# sourceMappingURL=base-agent.d.ts.map