@memberjunction/ai-agents 5.43.0 → 5.44.0

package/dist/base-agent.js

@@ -17,16 +17,23 @@ import { AIPromptRunner } from '@memberjunction/ai-prompts';
 import { BaseRealtimeModel, GetAIAPIKey } from '@memberjunction/ai';
 import { BaseAgentType } from './agent-types/base-agent-type.js';
 import { CopyScalarsAndArrays, JSONValidator, MJGlobal, SafeExpressionEvaluator, UUIDsEqual } from '@memberjunction/global';
+// token optimization via @memberjunction/context-crush (SmartCrusher/CacheAligner-inspired)
+import { CrushJSON, DescribeCrush, PartitionStablePrefix } from '@memberjunction/context-crush';
+// AST-aware code reduction (CodeCompressor-inspired) — opt-in per agent type
+import { CrushCode } from '@memberjunction/context-crush/code';
 import { RealtimeSessionRunner } from './realtime/realtime-session-runner.js';
 import { ResolveNarrationInstructionsTemplate } from './realtime/realtime-narration.js';
 import { BuildRealtimeOverridesJson, BuildVoiceMannerSection, GetNarrationPaceMs, GetProviderVoiceSettings, 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 { RealtimeRecordingController } from './realtime/realtime-recording-capture.js';
+import { resolveRecordingStorageAccountID, storeRealtimeRecording } from './realtime/realtime-recording-store.js';
 import { AIEngine } from '@memberjunction/aiengine';
 import { ActionEngineServer } from '@memberjunction/actions';
 import { AIAgentPermissionHelper } from '@memberjunction/ai-engine-base';
 import { AgentMemoryContextBuilder } from './agent-memory-context-builder.js';
-import { AIPromptParams, ChildPromptParam, ConversationUtility, ParseFileOutputRef, parseAssignmentStrategy, initAgentRunStep, finalizeAgentRunStep, AgentRunStepSaveQueue } from '@memberjunction/ai-core-plus';
+import { PromptComponentResolver, InjectScopedPromptParts } from './prompt-component-resolver.js';
+import { AIPromptParams, ChildPromptParam, ConversationUtility, ParseFileOutputRef, parseAssignmentStrategy, ResolveClientTools, initAgentRunStep, finalizeAgentRunStep, AgentRunStepSaveQueue } from '@memberjunction/ai-core-plus';
 import { AgentRunner } from './AgentRunner.js';
 import { PayloadManager } from './PayloadManager.js';
 import { ScratchpadManager } from './ScratchpadManager.js';
@@ -219,6 +226,37 @@ export class BaseAgent {
          * @since 2.123.0
          */
         this._effectiveActions = [];
+        /**
+         * Effective sub-agents available to this agent after applying subAgentChanges — the sub-agent
+         * counterpart of {@link _effectiveActions}. Populated during gatherPromptTemplateData() and used
+         * for validation in {@link validateSubAgentNextStep} via {@link getEffectiveSubAgentsForValidation}.
+         * Without this, a sub-agent added at runtime (e.g. by Skill activation) would be advertised in the
+         * prompt catalog but rejected as "not found" when the agent tried to actually use it.
+         * @private
+         */
+        this._effectiveSubAgents = [];
+        /**
+         * IDs of skills already activated during this run. Prevents re-activation from re-appending
+         * the same instructions to context / re-pushing duplicate actionChanges/subAgentChanges entries
+         * when the LLM references an already-active skill again.
+         * @private
+         */
+        this._activatedSkillIDs = [];
+        /**
+         * Whether Plan Mode is active for this run — resolved once in {@link initializeAgentRun} via
+         * {@link resolvePlanModeGate}. True only when `agent.SupportsPlanMode` (capability, default ON)
+         * AND `params.planMode` (per-request, default OFF) are both true AND this is a root agent.
+         * @private
+         */
+        this._planModeActive = false;
+        /**
+         * Whether Plan Mode's approval gate has already been satisfied for this run — either because
+         * Plan Mode isn't active, or because a prior linked run's Plan step was approved. When active
+         * and NOT yet approved, `validateNextStep` blocks Actions/Sub-Agent steps until a Plan step
+         * has been presented and approved.
+         * @private
+         */
+        this._planApproved = false;
         /**
          * Counts only prompt (LLM) executions, NOT all agent steps.
          * Used for message expiration age calculations so that `expirationTurns`
@@ -230,6 +268,14 @@ export class BaseAgent {
          * prompt execution occurred after them.
          */
         this._promptTurnCount = 0;
+        /**
+         * Per-run config for structurally compressing inline action-result payloads.
+         * Resolved once at run start from the agent-type prompt params (default on);
+         * read by formatActionResultsAsMarkdown so both the direct and loop callers
+         * share the same setting without threading it through every signature.
+         * @private
+         */
+        this._actionResultCrush = undefined;
         /**
          * Execution limits for dynamically added actions.
          * Maps action IDs to their MaxExecutionsPerRun limit.
@@ -256,6 +302,34 @@ export class BaseAgent {
          * @private
          */
         this.MAX_RECOVERY_ATTEMPTS = 1;
+        /**
+         * 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}.
+         */
+        // ── Realtime per-session capture state (scoped to one executeRealtimeSession run) ──────────
+        /**
+         * In-flight realtime turn rows keyed by transcript role (`'user'`/`'assistant'`), driving the
+         * create-on-start / update-on-complete persistence lifecycle. Reset at the start of every
+         * realtime session so a prior run can never leak an in-flight id into the next.
+         */
+        this.realtimeInFlightTurns = new Map();
+        /** Active audio recording controller for the current realtime session, or `null` when recording is off. */
+        this.realtimeRecording = null;
+        /** Storage account id the active recording stores to (RecordingStorageProviderID ?? AttachmentStorageProviderID). */
+        this.realtimeRecordingAccountId = null;
         /**
          * Storage for injected notes and examples to include in result
          */
@@ -427,6 +501,13 @@ export class BaseAgent {
      * @private
      */
     static { this.LARGE_BINARY_THRESHOLD = 10000; }
+    /**
+     * Minimum stringified length (chars) of an object/array action-result value before
+     * structural JSON compression (CrushJSON) is applied. Small payloads aren't worth a
+     * legend, so they pass through verbatim.
+     * @private
+     */
+    static { this.ACTION_RESULT_CRUSH_THRESHOLD = 600; }
     /**
      * Inspects a set of action output params for any value matching the FileOutputRef shape
      * (an object with `fileName`, `mimeType`, and either `fileData` or `fileId`).
@@ -1134,6 +1215,9 @@ export class BaseAgent {
                 this.InjectContextMemory(typeof inputText === 'string' ? inputText : '', params.agent, userId, companyId, params.contextUser, wrappedParams.conversationMessages, primaryScopeEntityId, primaryScopeRecordId, secondaryScopes, scopeConfig),
                 this.InjectPreExecutionRAG(typeof inputText === 'string' ? inputText : '', params.agent, params.contextUser, wrappedParams.conversationMessages, params.conversationMessages, primaryScopeEntityId, primaryScopeRecordId, secondaryScopes, params.payload)
             ]);
+            // Inject scope-resolved prompt parts (role-faithful) for this agent's prompt, alongside
+            // memory/RAG. Synchronous — parts are cached on AIEngine. Uses the same run scope.
+            this.InjectScopedPromptParts(params.agent, wrappedParams.conversationMessages, primaryScopeEntityId, primaryScopeRecordId, secondaryScopes);
             if (!config.success) {
                 this.logError(`Failed to load agent configuration: ${config.errorMessage}`, {
                     agent: params.agent,
@@ -1238,23 +1322,6 @@ export class BaseAgent {
     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);
@@ -1268,7 +1335,12 @@ export class BaseAgent {
         }
         // 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.
+        // 3) Resolve recording (OFF by default; runtime > agent > off; consent + storage gated) and reset
+        //    the per-session turn-lifecycle state, then build the injected deps and run the session.
+        this.realtimeInFlightTurns = new Map();
+        const recording = await this.resolveRealtimeRecording(params);
+        this.realtimeRecording = recording?.controller ?? null;
+        this.realtimeRecordingAccountId = recording?.storageAccountId ?? null;
         try {
             const deps = await this.buildRealtimeSessionDeps(params, config, modelResolution, promptRun);
             const runner = new RealtimeSessionRunner(deps);
@@ -1369,6 +1441,11 @@ export class BaseAgent {
             UserID: params.contextUser?.ID,
             DisableAutoResponse: meetingMode || undefined,
             SelfNames: selfNames,
+            // App awareness (Move 1/3/4): the app the session runs in (sources the app cascade layer +
+            // RelevantAgents → allowed-agent union) and the live app-context snapshot injected at mint.
+            // Both ride params.data, the same conduit async agents use for appContext.
+            ApplicationID: params.data?.applicationId?.trim() || undefined,
+            AppContext: params.data?.appContext,
         };
     }
     /**
@@ -1559,6 +1636,8 @@ export class BaseAgent {
             DelegateToTarget: (request) => this.delegateRealtimeToTarget(params, config, request),
             ExecuteTool: (call) => this.executeRealtimeTool(params, call),
             PersistTranscript: (transcript) => this.persistRealtimeTranscript(params, transcript),
+            Recording: this.realtimeRecording ?? undefined,
+            FinalizeRecording: () => this.finalizeRealtimeRecording(params),
             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.
@@ -1800,34 +1879,211 @@ export class BaseAgent {
         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).
+     * Persists a realtime transcript turn as a `ConversationDetail` with a **create-on-start /
+     * update-on-complete** lifecycle, so each turn carries both a start (`__mj_CreatedAt`) and an
+     * immutable end (`TurnEndedAt`):
+     * - **Interim** (`IsFinal=false`): on the FIRST delta for a role, CREATE the row with
+     *   `Status='In-Progress'` (so a live UI can show the turn streaming), stamping the recording-relative
+     *   `UtteranceStartMs` and the speaker `UserID` (user turns only). Subsequent interim deltas are no-ops.
+     * - **Final** (`IsFinal=true`): UPDATE that in-flight row with the full text, `Status='Complete'`,
+     *   `TurnEndedAt`, and `UtteranceEndMs`. If no interim was seen (some providers only emit final), the
+     *   row is created and finalized in one step.
+     *
+     * Returns the new row's ID the first time a DISTINCT turn is created, and `null` when an existing
+     * in-flight row is merely updated — the runner uses that to count turns (not events). User turns are
+     * `Role='User'`, assistant turns `Role='AI'`. When recording is active, `MediaType='Audio'` and the
+     * media-relative utterance offsets are stamped from the recording clock.
      *
-     * @param params The execution parameters (provides conversation id + context user).
-     * @param transcript The transcript turn emitted by the model.
+     * @param params The execution parameters (provides conversation id + context user + session id).
+     * @param transcript The transcript turn (interim delta or final) emitted by the model.
+     * @returns The created row id on first creation of a turn, else `null`.
      */
     async persistRealtimeTranscript(params, transcript) {
-        if (!transcript.IsFinal || !transcript.Text?.trim()) {
-            return;
+        if (!transcript.Text?.trim()) {
+            return null;
         }
         const conversationID = params.data?.conversationId;
         if (!conversationID) {
-            return; // Without a conversation we have nowhere to durably attach the turn.
+            return null; // 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';
+        const roleKey = transcript.Role; // 'user' | 'assistant'
+        const mjRole = transcript.Role === 'user' ? 'User' : 'AI';
+        // ── INTERIM: create the In-Progress row once per turn (first delta) ───────────────────────
+        if (!transcript.IsFinal) {
+            if (this.realtimeInFlightTurns.has(roleKey)) {
+                return null; // already created for this turn; ignore subsequent deltas
+            }
+            const detail = await md.GetEntityObject('MJ: Conversation Details', params.contextUser);
+            detail.NewRecord();
+            detail.ConversationID = conversationID;
+            detail.Role = mjRole;
+            detail.Message = transcript.Text;
+            detail.Status = 'In-Progress';
+            this.applyRealtimeTurnSpeakerAndMedia(detail, transcript, params, /*atStart*/ true);
+            if (params.agentSessionID) {
+                detail.AgentSessionID = params.agentSessionID;
+            }
+            if (!await detail.Save()) {
+                this.logError(`Failed to create in-progress realtime transcript turn: ${detail.LatestResult?.CompleteMessage ?? 'unknown error'}`, {
+                    agent: params.agent, category: 'RealtimeSession'
+                });
+                return null;
+            }
+            this.realtimeInFlightTurns.set(roleKey, detail.ID);
+            return detail.ID;
+        }
+        // ── FINAL: update the in-flight row (or create+finalize when no interim was seen) ─────────
+        const inFlightId = this.realtimeInFlightTurns.get(roleKey);
+        this.realtimeInFlightTurns.delete(roleKey);
+        let detail = await md.GetEntityObject('MJ: Conversation Details', params.contextUser);
+        let created = false;
+        if (inFlightId && await detail.Load(inFlightId)) {
+            // updating the existing streaming row → not a new turn
+        }
+        else {
+            detail.NewRecord();
+            detail.ConversationID = conversationID;
+            detail.Role = mjRole;
+            this.applyRealtimeTurnSpeakerAndMedia(detail, transcript, params, /*atStart*/ true);
+            if (params.agentSessionID) {
+                detail.AgentSessionID = params.agentSessionID;
+            }
+            created = true;
+        }
         detail.Message = transcript.Text;
-        if (params.agentSessionID) {
-            detail.AgentSessionID = params.agentSessionID;
+        detail.Status = 'Complete';
+        detail.TurnEndedAt = new Date();
+        if (this.realtimeRecording) {
+            detail.UtteranceEndMs = this.realtimeRecording.NowOffsetMs();
         }
         if (!await detail.Save()) {
-            this.logError(`Failed to persist realtime transcript turn: ${detail.LatestResult?.CompleteMessage ?? 'unknown error'}`, {
-                agent: params.agent,
-                category: 'RealtimeSession'
+            this.logError(`Failed to finalize realtime transcript turn: ${detail.LatestResult?.CompleteMessage ?? 'unknown error'}`, {
+                agent: params.agent, category: 'RealtimeSession'
+            });
+        }
+        return created ? detail.ID : null;
+    }
+    /**
+     * Stamps the speaker identity and recording-relative media fields on a freshly-created turn row.
+     * `UserID` is set only for **user** turns (an AI turn has no human speaker). When recording is
+     * active, `MediaType='Audio'` and `UtteranceStartMs` is captured from the recording clock.
+     *
+     * @param detail The new conversation-detail row.
+     * @param transcript The transcript turn.
+     * @param params The execution parameters.
+     * @param atStart Whether this is the turn's start (stamps `UtteranceStartMs`).
+     */
+    applyRealtimeTurnSpeakerAndMedia(detail, transcript, params, atStart) {
+        if (transcript.Role === 'user' && params.contextUser?.ID) {
+            detail.UserID = params.contextUser.ID;
+        }
+        if (this.realtimeRecording) {
+            detail.MediaType = 'Audio';
+            if (atStart) {
+                detail.UtteranceStartMs = this.realtimeRecording.NowOffsetMs();
+            }
+        }
+    }
+    /**
+     * Resolves whether to record this realtime session, OFF by default, with the precedence
+     * **runtime param > agent (`RecordingDefault`) > off**, hard-gated by consent and a resolvable
+     * storage provider. Returns the recording controller + the resolved storage account, or `null`
+     * to record nothing (fail-closed). Never throws — any resolution problem disables recording.
+     *
+     * Storage resolves to **`AIAgent.RecordingStorageProviderID` ?? `AIAgent.AttachmentStorageProviderID`**
+     * (recordings default to the attachments account), then to that provider's first account. With no
+     * provider configured, or consent not granted, recording is OFF.
+     *
+     * @param params The execution parameters (agent + runtime `data.recording`).
+     * @returns `{ controller, storageAccountId }` when recording is enabled, else `null`.
+     */
+    async resolveRealtimeRecording(params) {
+        try {
+            const agent = params.agent;
+            const runtime = (params.data?.recording ?? null);
+            // Media: runtime > agent default > off.
+            const rawMedia = runtime?.media ?? agent.RecordingDefault ?? 'None';
+            const media = rawMedia === 'Audio' || rawMedia === 'AudioVideo' ? rawMedia : 'None';
+            if (media === 'None') {
+                return null; // recording off
+            }
+            // Consent is a HARD gate — never record without explicit consent.
+            if (runtime?.consent !== true) {
+                this.logStatus('🔴 Realtime recording requested but consent was not granted — recording disabled.', false, params);
+                return null;
+            }
+            // Storage: recording provider, else attachment provider; then that provider's first account.
+            const storageAccountId = params.contextUser
+                ? await resolveRecordingStorageAccountID(agent, params.contextUser, params.provider || this._activeProvider)
+                : null;
+            if (!storageAccountId) {
+                this.logStatus('🔴 Realtime recording on but no resolvable storage account (RecordingStorageProviderID/AttachmentStorageProviderID) — recording disabled.', false, params);
+                return null;
+            }
+            const controller = new RealtimeRecordingController({ Media: media });
+            return { controller, storageAccountId };
+        }
+        catch (error) {
+            this.logError(`Failed to resolve realtime recording (recording disabled): ${error instanceof Error ? error.message : String(error)}`, {
+                agent: params.agent, category: 'RealtimeSession'
+            });
+            return null;
+        }
+    }
+    /**
+     * Finalizes the active recording after the session closes: encodes the captured audio to a WAV,
+     * stores it via MJStorage to the resolved account, links it to the `AIAgentSession` (via
+     * `MJ: File Entity Record Links`), and stamps `RecordingFileID` / `RecordingMedia` /
+     * `RecordingStartedAt` on the session. Never throws — a recording failure must not fail the
+     * session run. No-op when recording is off, nothing was captured, or there is no session id.
+     *
+     * @param params The execution parameters (provides the session id + context user + provider).
+     */
+    async finalizeRealtimeRecording(params) {
+        const controller = this.realtimeRecording;
+        if (!controller) {
+            return;
+        }
+        // One-shot: clear instance state up front so a re-entrant/duplicate Stop can't double-store.
+        this.realtimeRecording = null;
+        const storageAccountId = this.realtimeRecordingAccountId;
+        this.realtimeRecordingAccountId = null;
+        try {
+            controller.Stop();
+            const sessionID = params.agentSessionID;
+            const contextUser = params.contextUser;
+            if (!sessionID || !storageAccountId || !contextUser) {
+                return; // nowhere to attach / store (or no user context to store under)
+            }
+            const encoded = controller.EncodeWav();
+            if (!encoded) {
+                this.logStatus('🔇 Realtime session produced no audio to record.', true, params);
+                return;
+            }
+            const md = params.provider || this._activeProvider;
+            // Capture-time waveform peaks (max-abs per bucket, normalized 0..1) computed from the
+            // same mixed PCM as the WAV — persisted as a peaks.json sidecar so the player renders the
+            // real waveform without re-decoding the audio. Best-effort: an empty array writes no sidecar.
+            const peaks = controller.GetPeaks();
+            const fileID = await storeRealtimeRecording({
+                Audio: encoded.Buffer,
+                MimeType: 'audio/wav',
+                Media: controller.Media,
+                StartedAt: controller.StartedAt ?? new Date(),
+                StorageAccountID: storageAccountId,
+                SessionID: sessionID,
+                ContextUser: contextUser,
+                Provider: md,
+                Peaks: peaks.length > 0 ? peaks : undefined
+            });
+            if (fileID) {
+                this.logStatus(`🎬 Realtime recording stored (${Math.round(encoded.DurationMs / 1000)}s, file ${fileID}).`, true, params);
+            }
+        }
+        catch (error) {
+            this.logError(`Failed to finalize realtime recording: ${error instanceof Error ? error.message : String(error)}`, {
+                agent: params.agent, category: 'RealtimeSession'
             });
         }
     }
@@ -2093,6 +2349,32 @@ export class BaseAgent {
         this._injectedMemory = result;
         return result;
     }
+    /**
+     * Inject this agent's scoped prompt parts into the conversation, role-faithfully.
+     *
+     * Parallels {@link InjectContextMemory}: resolves `MJ: Scoped Prompt Parts` for the agent's
+     * primary prompt under the run's polymorphic scope (the SAME PrimaryScope/SecondaryScopes the
+     * runtime threads for memory), and unshifts the assembled role-tagged messages onto
+     * `conversationMessages`. In-memory + synchronous (parts are cached on `AIEngine`). No-op when
+     * the agent has no active prompt or no parts resolve for the scope.
+     */
+    InjectScopedPromptParts(agent, conversationMessages, primaryScopeEntityId, primaryScopeRecordId, secondaryScopes) {
+        try {
+            const prompts = AIEngine.Instance.AgentPrompts
+                .filter(ap => UUIDsEqual(ap.AgentID, agent.ID) && ap.Status === 'Active')
+                .sort((a, b) => (a.ExecutionOrder ?? 0) - (b.ExecutionOrder ?? 0));
+            if (prompts.length === 0)
+                return;
+            // Obtain the (possibly downstream-overridden) resolver via the class factory, so any
+            // consumer can plug in custom inclusion/scope logic by subclassing PromptComponentResolver.
+            const resolver = MJGlobal.Instance.ClassFactory.CreateInstance(PromptComponentResolver) ??
+                new PromptComponentResolver();
+            InjectScopedPromptParts(resolver, prompts[0].PromptID, { primaryScopeEntityId, primaryScopeRecordId, secondaryScopes }, conversationMessages);
+        }
+        catch (e) {
+            this.logError(e instanceof Error ? e : new Error(String(e)), { category: 'ScopedPromptParts' });
+        }
+    }
     /**
      * Inject pre-execution RAG context for this agent using scoped search.
      *
@@ -2608,6 +2890,20 @@ export class BaseAgent {
      * @returns
      */
     async validateNextStep(params, nextStep, currentPayload, agentRun, currentStep) {
+        // Plan Mode enforcement: while active and not yet approved, block Actions/Sub-Agent so the
+        // agent cannot skip straight to execution — it must present a Plan first. Chat, Retry,
+        // Skill activation, ForEach/While, and ClientTools are all still allowed (e.g. asking a
+        // clarifying question, or loading a skill's instructions, before forming the plan).
+        if (this._planModeActive && !this._planApproved && (nextStep.step === 'Actions' || nextStep.step === 'Sub-Agent')) {
+            // nextStep.step is narrowed to 'Actions' | 'Sub-Agent' here, so it can never already be
+            // 'Retry' — always increment (we're demoting it to Retry from a non-retry step).
+            this._generalValidationRetryCount++;
+            return {
+                step: 'Retry',
+                terminate: false,
+                errorMessage: 'Plan mode is active for this request. Present your plan first via a "Plan" next step and wait for approval before executing actions or sub-agents.'
+            };
+        }
         // for next step, let's do a little quick validation here for sub-agent and actions to ensure requests are valid
         switch (nextStep.step) {
             case 'Sub-Agent':
@@ -2628,6 +2924,15 @@ export class BaseAgent {
             case 'While':
                 // While loops are valid - no additional validation needed
                 return nextStep;
+            // Type assertion required because 'Skill' is not part of the BaseAgentNextStep step
+            // union (it's non-terminal, like 'ClientTools' — see the type's doc comment).
+            case 'Skill':
+                return this.validateSkillNextStep(params, nextStep, currentPayload, agentRun, currentStep);
+            // Type assertion required because 'Plan' is not part of the BaseAgentNextStep step
+            // union (it's non-terminal — the terminal step it produces is 'Chat', see
+            // executePlanStep's doc comment for why).
+            case 'Plan':
+                return this.validatePlanNextStep(params, nextStep, currentPayload, agentRun, currentStep);
             case 'ClientTools':
                 // Client tools are valid - execution handled by executeClientToolsStep
                 return nextStep;
@@ -2670,7 +2975,7 @@ export class BaseAgent {
         return nextStep.subAgent ? [nextStep.subAgent] : [];
     }
     async validateSubAgentNextStep(params, nextStep, currentPayload, agentRun, currentStep) {
-        const curAgentSubAgents = AIEngine.Instance.GetSubAgents(params.agent.ID, 'Active');
+        const curAgentSubAgents = this.getEffectiveSubAgentsForValidation(params.agent.ID);
         // Collect requested sub-agents. Prefer plural `subAgents` (parallel fan-out);
         // fall back to singular `subAgent` for the classic single-sub-agent next step.
         const requested = this.getRequestedSubAgents(nextStep);
@@ -2849,6 +3154,95 @@ export class BaseAgent {
         const agentActions = AIEngine.Instance.AgentActions.filter(aa => UUIDsEqual(aa.AgentID, agentId) && aa.Status === 'Active');
         return ActionEngineServer.Instance.Actions.filter(a => agentActions.some(aa => UUIDsEqual(aa.ActionID, a.ID)) && a.Status === 'Active');
     }
+    /**
+     * Gets the effective sub-agents for validation, using runtime subAgentChanges if available.
+     * Falls back to the database-configured relationship set if _effectiveSubAgents is empty.
+     * Mirrors {@link getEffectiveActionsForValidation}.
+     *
+     * @param agentId - The ID of the agent to get sub-agents for
+     * @returns Array of effective sub-agents available to the agent
+     * @protected
+     */
+    getEffectiveSubAgentsForValidation(agentId) {
+        if (this._effectiveSubAgents.length > 0) {
+            return this._effectiveSubAgents;
+        }
+        // Fallback: compute from database configuration (ParentID children + AgentRelationships)
+        return AIEngine.Instance.GetSubAgents(agentId, 'Active');
+    }
+    /**
+     * Validates that the requested skill(s) are known and allowed for this agent (resolved via
+     * {@link AIEngine.GetSkillsForAgent}, which enforces the agent's AcceptsSkills gate + the
+     * catalog/grant Status chain). Subclasses can override to implement custom validation logic.
+     *
+     * Mirrors {@link validateActionsNextStep}'s fuzzy-name-matching UX: an exact case-insensitive
+     * match is tried first, falling back to a CONTAINS match when exactly one candidate matches.
+     *
+     * @protected
+     */
+    async validateSkillNextStep(params, nextStep, currentPayload, agentRun, currentStep) {
+        const requested = nextStep.skillActivations ?? [];
+        if (requested.length === 0) {
+            if (nextStep.step !== 'Retry') {
+                this._generalValidationRetryCount++;
+            }
+            return {
+                step: 'Retry',
+                terminate: false,
+                errorMessage: 'When activating a skill, 1 or more skills must be specified'
+            };
+        }
+        const availableSkills = AIEngine.Instance.GetSkillsForAgent(params.agent, params.contextUser);
+        const missingSkills = requested.filter(req => {
+            const requestedName = req.name.trim().toLowerCase();
+            const exactMatch = availableSkills.find(s => s.Name.trim().toLowerCase() === requestedName);
+            if (exactMatch)
+                return false;
+            const containsMatches = availableSkills.filter(s => s.Name.trim().toLowerCase().includes(requestedName));
+            if (containsMatches.length === 1) {
+                this.logStatus(`Skill name fuzzy matched: '${req.name}' → '${containsMatches[0].Name}'`, true, params);
+                req.name = containsMatches[0].Name;
+                return false;
+            }
+            return true;
+        });
+        if (missingSkills.length > 0) {
+            const missingNames = missingSkills.map(s => s.name).join(', ');
+            const availableNames = availableSkills.map(s => s.Name).join(', ') || '(none)';
+            this.logError(`Skill(s) '${missingNames}' not found or not available for agent '${params.agent.Name}'. Available: ${availableNames}`, {
+                agent: params.agent,
+                category: 'SkillExecution'
+            });
+            if (nextStep.step !== 'Retry') {
+                this._generalValidationRetryCount++;
+            }
+            return {
+                step: 'Retry',
+                terminate: false,
+                errorMessage: `Skill(s) '${missingNames}' not found or not available. Available: ${availableNames}`
+            };
+        }
+        return nextStep;
+    }
+    /**
+     * Validates that a 'Plan' next step (Plan Mode) has plan text to present. Subclasses can
+     * override to add additional plan-quality checks (e.g. minimum length, required sections).
+     *
+     * @protected
+     */
+    async validatePlanNextStep(params, nextStep, currentPayload, agentRun, currentStep) {
+        if (!nextStep.planDetails?.plan || nextStep.planDetails.plan.trim().length === 0) {
+            if (nextStep.step !== 'Retry') {
+                this._generalValidationRetryCount++;
+            }
+            return {
+                step: 'Retry',
+                terminate: false,
+                errorMessage: 'Plan text is required when presenting a Plan for approval'
+            };
+        }
+        return nextStep;
+    }
     /**
      * Validates that the Success next step is valid and can be executed by the current agent. Subclasses can override
      * this method to implement custom validation logic if needed.
@@ -4367,6 +4761,8 @@ The context is now within limits. Please retry your request with the recovered c
             }
             // Store for later validation in executeActionsStep
             this._effectiveActions = activeActions;
+            // Store for later validation in validateSubAgentNextStep (see getEffectiveSubAgentsForValidation)
+            this._effectiveSubAgents = uniqueActiveSubAgents;
             // Agent type prompt params: reuse cached base merge unless a runtime override is present.
             const runtimePromptParamOverrides = extraData?.__agentTypePromptParams;
             let agentTypePromptParams;
@@ -4385,6 +4781,13 @@ The context is now within limits. Please retry your request with the recovered c
             const clientToolDetails = this.buildClientToolPromptSection(agent, extraData);
             // Build app context section if provided in extraData
             const appContext = this.buildAppContextSection(extraData);
+            // Skill catalog (name + description only — progressive disclosure). Empty for
+            // AcceptsSkills='None' since GetSkillsForAgent already returns [] in that case.
+            // Filtered by the acting user's Run permission (open-by-default) so the agent is
+            // never even offered a skill the user isn't entitled to — the permission boundary
+            // is enforced at the catalog, not just at activation.
+            const availableSkills = engine.GetSkillsForAgent(agent, _contextUser);
+            const skillsCatalog = this.formatSkillsCatalog(availableSkills);
             const contextData = {
                 agentName: agent.Name,
                 agentDescription: agent.Description,
@@ -4394,6 +4797,10 @@ The context is now within limits. Please retry your request with the recovered c
                 actionCount: activeActions.length,
                 actionDetails: actionDetails,
                 clientToolDetails: clientToolDetails,
+                skillCount: availableSkills.length,
+                skillsCatalog: skillsCatalog,
+                planModeActive: this._planModeActive,
+                planApproved: this._planApproved,
                 appContext: appContext,
             };
             // Build the final result with __agentTypePromptParams injected
@@ -4925,6 +5332,17 @@ The context is now within limits. Please retry your request with the recovered c
             return line;
         }).join('\n');
     }
+    /**
+     * Formats the skill CATALOG as compact markdown — name + description ONLY. This is
+     * progressive disclosure by design: the LLM sees just enough to decide whether to activate a
+     * skill (via a 'Skill' next step), but never sees `Instructions` until it does. Instructions
+     * are appended separately in {@link buildSkillActivationMessage} on activation.
+     *
+     * @private
+     */
+    formatSkillsCatalog(skills) {
+        return skills.map(s => `- **${s.Name}** — ${s.Description ?? '(no description)'}`).join('\n');
+    }
     /**
      * Utility method to get agent prompt parameters for a given agent. This gets the
      * highest priority prompt for the agent, and then gets the parameters for that
@@ -5000,44 +5418,41 @@ The context is now within limits. Please retry your request with the recovered c
     /**
      * Build the client tool prompt section for system prompt injection.
      *
-     * Tool sources (checked in order, all merged — first registration wins):
-     * 1. Metadata tools from AI Agent Client Tools junction table
-     * 2. Session-level enriched tools from ClientToolRequestManager (set by client SDK)
-     * 3. Tools provided directly in extraData.clientTools (runtime override)
+     * Resolution is delegated to the shared, tier-agnostic {@link ResolveClientTools}
+     * (`@memberjunction/ai-core-plus`) — the single source of truth used by the async
+     * path (here), the realtime co-agent broker, and the conversations runtime. Tiers,
+     * highest precedence first:
+     *
+     * 1. **override** — tools passed directly in the run's `data.clientTools`
+     * 2. **session (dynamic)** — client-SDK enriched tools from {@link ClientToolRequestManager}
+     * 3. **app** — tools the active surface published in the app-context capability manifest
+     * 4. **static** — the agent's metadata tools from the `AI Agent Client Tools` junction
+     *
+     * NOTE (behavior change): the previous inline merge resolved *static-wins* (metadata
+     * was added first and won name collisions). The unified resolver uses the more-correct
+     * *override > session > app > static* — a runtime/dynamic tool now overrides a stale
+     * static metadata tool of the same name. Collisions are rare in practice.
      */
     buildClientToolPromptSection(agent, extraData) {
-        const toolMap = new Map();
-        // 1. Metadata tools from junction table (authoritative source)
+        // Static tier — agent's metadata tools from the AI Agent Client Tools junction.
         const engine = AIEngine.Instance;
-        const metadataTools = engine.GetClientToolsForAgent(agent.ID);
-        for (const tool of metadataTools) {
-            toolMap.set(tool.Name, {
-                Name: tool.Name,
-                Description: tool.Description,
-                InputSchema: tool.InputSchemaJSON ? JSON.parse(tool.InputSchemaJSON) : {},
-                OutputSchema: tool.OutputSchemaJSON ? JSON.parse(tool.OutputSchemaJSON) : undefined,
-                Category: tool.Category || undefined,
-                DefaultTimeoutMs: tool.DefaultTimeoutMs || undefined
-            });
-        }
-        // 2. Session-level enriched tools (client SDK decorated tools)
+        const staticTools = engine.GetClientToolsForAgent(agent.ID).map(tool => ({
+            Name: tool.Name,
+            Description: tool.Description,
+            InputSchema: tool.InputSchemaJSON ? JSON.parse(tool.InputSchemaJSON) : {},
+            OutputSchema: tool.OutputSchemaJSON ? JSON.parse(tool.OutputSchemaJSON) : undefined,
+            Category: tool.Category || undefined,
+            DefaultTimeoutMs: tool.DefaultTimeoutMs || undefined
+        }));
+        // Dynamic (session) tier — client-SDK enriched tools for this session.
         const sessionID = extraData?.sessionID;
-        if (sessionID) {
-            for (const tool of ClientToolRequestManager.Instance.GetSessionTools(sessionID)) {
-                if (!toolMap.has(tool.Name)) {
-                    toolMap.set(tool.Name, tool);
-                }
-            }
-        }
-        // 3. Runtime extraData override
-        if (extraData?.clientTools) {
-            for (const tool of extraData.clientTools) {
-                if (!toolMap.has(tool.Name)) {
-                    toolMap.set(tool.Name, tool);
-                }
-            }
-        }
-        const tools = Array.from(toolMap.values());
+        const sessionTools = sessionID ? ClientToolRequestManager.Instance.GetSessionTools(sessionID) : [];
+        // App tier — tools the active surface published in the app-context capability manifest.
+        const appContext = extraData?.appContext;
+        const appTools = appContext?.Capabilities?.Tools ?? [];
+        // Override tier — tools passed directly in the run's data.
+        const overrideTools = extraData?.clientTools ?? [];
+        const tools = ResolveClientTools({ agentId: agent.ID, staticTools, sessionTools, appTools, overrideTools });
         if (tools.length === 0) {
             return ''; // No client tools available
         }
@@ -5234,19 +5649,112 @@ The context is now within limits. Please retry your request with the recovered c
         if (typeof value === 'boolean' || typeof value === 'number') {
             return `\`${String(value)}\``;
         }
-        let stringValue;
         if (typeof value === 'string') {
-            stringValue = value;
-        }
-        else {
-            // Compact JSON (no pretty-printing) for objects/arrays
-            stringValue = JSON.stringify(value);
+            // A string param may carry JSON (many actions JSON.stringify their payloads),
+            // SQL/TS code, or plain text. Try structural JSON compression first — it is a
+            // safe no-op on non-JSON (crushParamValue's internal JSON.parse failure is
+            // caught and returns null) — then opt-in AST code reduction (SQL/TS), then pass
+            // through (optionally length-capped).
+            const crushedJson = this.crushParamValue(value);
+            if (crushedJson !== null) {
+                return crushedJson;
+            }
+            const crushedCode = this.crushCodeValue(value);
+            if (crushedCode !== null) {
+                return crushedCode;
+            }
+            return maxLength > 0 && value.length > maxLength ? `${value.substring(0, maxLength)}…` : value;
+        }
+        // Objects/arrays: compact JSON (no pretty-printing), optionally structurally
+        // compressed via context-crush when crushing is enabled and the value is large.
+        const stringValue = JSON.stringify(value);
+        const crushed = this.crushParamValue(stringValue);
+        if (crushed !== null) {
+            return crushed;
         }
         if (maxLength > 0 && stringValue.length > maxLength) {
             return `${stringValue.substring(0, maxLength)}…`;
         }
         return stringValue;
     }
+    /**
+     * Resolve the per-run action-result compression config from the agent-type prompt
+     * params. Crushing is on by default and only disabled when an agent explicitly sets
+     * `crushActionResults: false`, mirroring the `includeXxxDocs` opt-out convention.
+     * @private
+     */
+    resolveActionResultCrush(params) {
+        const agentTypePromptParams = params.data?.__agentTypePromptParams;
+        if (agentTypePromptParams?.crushActionResults === false) {
+            return undefined;
+        }
+        const requestedLang = agentTypePromptParams?.crushCodeLang;
+        const codeLang = requestedLang === 'sql' || requestedLang === 'typescript' ? requestedLang : undefined;
+        return { threshold: BaseAgent.ACTION_RESULT_CRUSH_THRESHOLD, maxChars: undefined, codeLang };
+    }
+    /**
+     * AST-reduce a large code-string action-result value when the agent opted into a code
+     * language (via `crushCodeLang` or a subclass override) and the value clears the size
+     * threshold. Returns reduced code plus a one-line legend, or null to keep the string
+     * verbatim (crushing disabled, too small, or no net saving).
+     *
+     * token optimization via @memberjunction/context-crush (CodeCompressor-inspired)
+     * @private
+     */
+    crushCodeValue(stringValue) {
+        const config = this._actionResultCrush;
+        if (!config || !config.codeLang || stringValue.length < config.threshold) {
+            return null;
+        }
+        // Crushing is a best-effort optimization — it must never break an agent turn. Any
+        // failure falls back to the verbatim value.
+        try {
+            const result = CrushCode(stringValue, config.codeLang);
+            if (result.CrushedChars >= result.OriginalChars) {
+                return null;
+            }
+            const legend = DescribeCrush(result);
+            return legend ? `${result.Text}\n  ↳ ${legend}` : result.Text;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Structurally compress a JSON action-result value when crushing is enabled for the run
+     * and the value clears the size threshold. Accepts either the `JSON.stringify` of an
+     * object/array param, or a raw string param that itself contains JSON (many actions
+     * stringify their payloads, e.g. `run-adhoc-query`'s `Results`). Returns crushed text
+     * plus a one-line legend, or null when crushing is disabled, the value is too small, the
+     * value isn't valid JSON, or compression wouldn't actually save characters — so callers
+     * fall back to verbatim (and, for strings, to code crushing) behavior.
+     *
+     * token optimization via @memberjunction/context-crush (SmartCrusher-inspired)
+     * @private
+     */
+    crushParamValue(stringValue) {
+        const config = this._actionResultCrush;
+        if (!config || stringValue.length < config.threshold) {
+            return null;
+        }
+        // Crushing is a best-effort optimization — it must never break an agent turn. Any
+        // failure (non-JSON input, pathologically deep payloads) falls back to verbatim.
+        try {
+            // Parse to a plain JSON value. This is the JSON.stringify of an object/array
+            // param, or a raw string param that contains JSON; non-JSON strings throw here
+            // and are caught below (caller then tries code crushing / verbatim).
+            const json = JSON.parse(stringValue);
+            const result = CrushJSON(json, { MaxChars: config.maxChars });
+            if (result.CrushedChars >= result.OriginalChars) {
+                return null; // no net saving — keep the verbatim JSON
+            }
+            const legend = DescribeCrush(result);
+            return legend ? `${result.Text}\n  ↳ ${legend}` : result.Text;
+        }
+        catch {
+            return null;
+        }
+    }
     /**
      * Formats a parameter value for display in action execution messages.
      * Truncates long strings and formats objects/arrays for readability.
@@ -5458,6 +5966,9 @@ The context is now within limits. Please retry your request with the recovered c
         }
         // Reset prompt turn counter for this execution
         this._promptTurnCount = 0;
+        // Resolve action-result compression config for this run (default on; opt out via
+        // crushActionResults: false in the agent-type prompt params).
+        this._actionResultCrush = this.resolveActionResultCrush(params);
         // Create MJAIAgentRunEntity
         this._agentRun = await (params.provider || this._activeProvider).GetEntityObject('MJ: AI Agent Runs', params.contextUser);
         this._agentRun.AgentID = params.agent.ID;
@@ -5581,6 +6092,15 @@ The context is now within limits. Please retry your request with the recovered c
             : [params.agent.Name || 'Unknown Agent'];
         this._depth = params.parentDepth !== undefined ? params.parentDepth + 1 : 0;
         this._parentStepCounts = params.parentStepCounts || [];
+        // Resolve Plan Mode gate state for this run (must happen before the main loop starts —
+        // gatherPromptTemplateData/validateNextStep both read _planModeActive/_planApproved — and
+        // after _depth is set above, since the gate only applies to root agents).
+        const planModeGate = await this.resolvePlanModeGate(params);
+        this._planModeActive = planModeGate.active;
+        this._planApproved = planModeGate.approved;
+        // Pre-activate any user-requested skills (from a `/skill-name` composer mention). Must run
+        // after _depth is set (root-only) and after the run is persisted (records a Skill step).
+        await this.preActivateRequestedSkills(params);
         // Reset execution chain and progress tracking
         this._allProgressSteps = [];
         // Update params with the modified payload if auto-populated
@@ -5590,6 +6110,62 @@ The context is now within limits. Please retry your request with the recovered c
             params.payload = modifiedParams.payload;
         }
     }
+    /**
+     * Resolves whether Plan Mode is active for this run, and whether its approval gate is already
+     * satisfied. Called once from {@link initializeAgentRun}, after `_depth` is set.
+     *
+     * - `active`: `agent.SupportsPlanMode` (capability, default ON/opt-out) AND `params.planMode`
+     *   (per-request, default OFF) AND this is a root agent (`_depth === 0`). Sub-agents never gate
+     *   on Plan Mode — only the top-level agent the user/caller invoked does.
+     * - `approved`: only meaningful when `active`. True when `params.lastRunId` points to a prior
+     *   run whose Plan step's `MJ: AI Agent Requests` row resolved to `Approved` or `Responded`
+     *   (a `Rejected` plan — or no matching request at all — leaves the gate unsatisfied, sending
+     *   the agent back to present a revised plan).
+     *
+     * Override to change Plan Mode eligibility rules (e.g. gate on a specific agent category).
+     *
+     * @protected
+     */
+    async resolvePlanModeGate(params) {
+        const active = !!(params.agent.SupportsPlanMode && params.planMode === true && this._depth === 0);
+        if (!active) {
+            return { active: false, approved: false };
+        }
+        if (!params.lastRunId) {
+            return { active: true, approved: false };
+        }
+        const rv = new RunView();
+        const requestResult = await rv.RunView({
+            EntityName: 'MJ: AI Agent Requests',
+            ExtraFilter: `OriginatingAgentRunID='${params.lastRunId}'`,
+            Fields: ['Status', 'OriginatingAgentRunStepID'],
+            OrderBy: '__mj_CreatedAt DESC',
+            MaxRows: 1,
+            ResultType: 'simple'
+        }, params.contextUser);
+        if (!requestResult.Success || requestResult.Results.length === 0) {
+            return { active: true, approved: false };
+        }
+        const request = requestResult.Results[0];
+        const resolved = request.Status === 'Approved' || request.Status === 'Responded';
+        if (!resolved || !request.OriginatingAgentRunStepID) {
+            return { active: true, approved: false };
+        }
+        // Confirm the request actually originated from a Plan step — a resolved request from an
+        // unrelated Chat clarification (asked before the agent could even form a plan) must NOT
+        // satisfy the Plan Mode gate.
+        const stepResult = await rv.RunView({
+            EntityName: 'MJ: AI Agent Run Steps',
+            ExtraFilter: `ID='${request.OriginatingAgentRunStepID}'`,
+            Fields: ['StepType'],
+            MaxRows: 1,
+            ResultType: 'simple'
+        }, params.contextUser);
+        const approved = stepResult.Success
+            && stepResult.Results.length > 0
+            && stepResult.Results[0].StepType === 'Plan';
+        return { active: true, approved };
+    }
     /**
      * Validates the agent with tracking.
      *
@@ -5666,7 +6242,13 @@ The context is now within limits. Please retry your request with the recovered c
         });
         // 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);
+        // When the step has a parent, chain the INSERT AFTER the parent's INSERT to satisfy the
+        // self-referencing FK_AIAgentRunStep_ParentID constraint — without this, a child INSERT that
+        // races the parent INSERT hits an FK violation (especially under large-payload parent INSERTs).
+        const parentStepEntity = params.parentId && this._agentRun?.Steps
+            ? this._agentRun.Steps.find(s => UUIDsEqual(s.ID, params.parentId))
+            : undefined;
+        this._stepSaveQueue.Insert(stepEntity, parentStepEntity);
         // Add the step to the agent run's Steps array
         if (this._agentRun) {
             this._agentRun.Steps.push(stepEntity);
@@ -5941,6 +6523,16 @@ The context is now within limits. Please retry your request with the recovered c
                 return await this.processSubAgentStep(params, previousDecision, undefined, undefined, stepCount);
             case 'Actions':
                 return await this.executeActionsStep(params, previousDecision, undefined, true, stepCount);
+            // Type assertion required because 'Skill' is not part of the BaseAgentNextStep step
+            // union (non-terminal, like 'ClientTools') — LoopAgentType.DetermineNextStep() emits it
+            // when the LLM chooses to activate a skill.
+            case 'Skill':
+                return await this.executeSkillStep(params, config, previousDecision, stepCount);
+            // Type assertion required because 'Plan' is not part of the BaseAgentNextStep step
+            // union — LoopAgentType.DetermineNextStep() emits it when the LLM presents a plan
+            // (Plan Mode). executePlanStep's terminal return is 'Chat'-shaped (see its doc comment).
+            case 'Plan':
+                return await this.executePlanStep(params, previousDecision);
             // Type assertion required because 'ClientTools' is not part of the BaseAgentNextStep
             // step union — LoopAgentType.DetermineNextStep() emits it when the LLM chooses client tools.
             case 'ClientTools':
@@ -8097,6 +8689,315 @@ The context is now within limits. Please retry your request with the recovered c
         });
         return `${header}\n${lines.join('\n')}`;
     }
+    /**
+     * Executes a 'Skill' next step: activates one or more skills the LLM requested by name.
+     * Activating a skill (1) appends its full `Instructions` to the conversation so they take
+     * effect for the remainder of the run, and (2) enables its bundled Actions/sub-agents by
+     * pushing `root`-scoped `add` entries onto `params.actionChanges`/`params.subAgentChanges` —
+     * the same runtime tool-surface-extension mechanism `ExecuteAgentParams` already exposes to
+     * external callers. This is NOT a nested agent run; it never terminates the loop itself.
+     *
+     * Already-activated skills (tracked in `_activatedSkillIDs`) are skipped — re-requesting an
+     * active skill is a harmless no-op rather than re-appending duplicate instructions.
+     *
+     * Decomposed into {@link resolveSkillActivations}, {@link buildSkillActivationMessage},
+     * {@link enableSkillCapabilities}, and {@link recordSkillActivationStep} — override any of
+     * those for fine-grained control (e.g. custom instruction formatting, additional side effects
+     * on activation) without re-implementing the whole step.
+     *
+     * @protected
+     */
+    async executeSkillStep(params, config, previousDecision, stepCount = 0) {
+        const requested = previousDecision.skillActivations ?? [];
+        if (requested.length === 0) {
+            // Nothing to activate — continue with next prompt
+            return await this.executePromptStep(params, config, previousDecision, stepCount);
+        }
+        const resolvedSkills = this.resolveSkillActivations(requested, params.agent, params.contextUser);
+        const newlyActivated = resolvedSkills.filter(skill => !this._activatedSkillIDs.some(id => UUIDsEqual(id, skill.ID)));
+        if (newlyActivated.length === 0) {
+            // All requested skills are already active this run — no-op, just continue
+            return await this.executePromptStep(params, config, previousDecision, stepCount);
+        }
+        const currentPayload = previousDecision?.newPayload || previousDecision?.previousPayload || params.payload;
+        for (const skill of newlyActivated) {
+            await this.recordSkillActivationStep(skill, currentPayload, params);
+            this.enableSkillCapabilities(skill, params);
+            this._activatedSkillIDs.push(skill.ID);
+        }
+        const activationMessage = this.buildSkillActivationMessage(newlyActivated);
+        params.conversationMessages.push({
+            role: 'user',
+            content: activationMessage,
+            metadata: {
+                turnAdded: this._promptTurnCount,
+                messageType: 'skill-activation'
+            }
+        });
+        return await this.executePromptStep(params, config, previousDecision, stepCount);
+    }
+    /**
+     * Pre-activates skills the caller explicitly requested via {@link ExecuteAgentParams.requestedSkillIDs}
+     * (typically an end user's `/skill-name` composer mentions), at run start — so their Instructions
+     * and bundled Actions/sub-agents take effect from the first turn rather than waiting for the model
+     * to discover and activate them through the catalog.
+     *
+     * **Root-agent only** (skills never cascade to sub-agents), and each requested skill activates
+     * **only if it survives the guard**: it must be in the set {@link AIEngine.GetSkillsForAgent}
+     * allows for this agent (the AcceptsSkills gate) AND the acting user must have Run permission on it
+     * — both enforced by passing `params.contextUser` to `GetSkillsForAgent`. Requested IDs that fail
+     * either check are silently dropped, so a client can never force-activate a skill the user or agent
+     * isn't entitled to. Reuses the same {@link recordSkillActivationStep} / {@link enableSkillCapabilities}
+     * / {@link buildSkillActivationMessage} machinery as the model-initiated `Skill` step, so activation
+     * is recorded and takes effect identically. Plan Mode is unaffected — pre-activation widens the tool
+     * surface, but the plan-approval gate still blocks executing those tools until the plan is approved.
+     *
+     * @protected
+     */
+    async preActivateRequestedSkills(params) {
+        if (this._depth !== 0) {
+            return; // skills are root-agent only; never pre-activate on sub-agents
+        }
+        const requestedIds = params.requestedSkillIDs;
+        if (!requestedIds || requestedIds.length === 0) {
+            return;
+        }
+        // Guard: intersect the requested IDs with the agent-accepted ∩ user-permitted set.
+        const allowed = AIEngine.Instance.GetSkillsForAgent(params.agent, params.contextUser);
+        const newlyActivated = allowed.filter(s => requestedIds.some(id => UUIDsEqual(id, s.ID)) &&
+            !this._activatedSkillIDs.some(id => UUIDsEqual(id, s.ID)));
+        if (newlyActivated.length === 0) {
+            return;
+        }
+        const currentPayload = params.payload;
+        for (const skill of newlyActivated) {
+            await this.recordSkillActivationStep(skill, currentPayload, params);
+            this.enableSkillCapabilities(skill, params);
+            this._activatedSkillIDs.push(skill.ID);
+        }
+        const activationMessage = this.buildSkillActivationMessage(newlyActivated);
+        if (!params.conversationMessages) {
+            params.conversationMessages = [];
+        }
+        params.conversationMessages.push({
+            role: 'user',
+            content: activationMessage,
+            metadata: {
+                turnAdded: this._promptTurnCount,
+                messageType: 'skill-activation'
+            }
+        });
+    }
+    /**
+     * Resolves the LLM's requested skill names to `MJ: AI Skills` entities, restricted to what
+     * {@link AIEngine.GetSkillsForAgent} allows for this agent (the AcceptsSkills gate + Status
+     * chain). Names that don't resolve are silently dropped here — {@link validateSkillNextStep}
+     * is responsible for rejecting unknown/disallowed names before execution ever reaches this
+     * point, so by the time `executeSkillStep` runs, every requested name is expected to match.
+     *
+     * Override to change resolution semantics (e.g. resolve by ID instead of Name).
+     *
+     * @protected
+     */
+    resolveSkillActivations(requested, agent, contextUser) {
+        const availableSkills = AIEngine.Instance.GetSkillsForAgent(agent, contextUser);
+        const resolved = [];
+        for (const req of requested) {
+            const requestedName = req.name.trim().toLowerCase();
+            const match = availableSkills.find(s => s.Name.trim().toLowerCase() === requestedName);
+            if (match && !resolved.some(s => UUIDsEqual(s.ID, match.ID))) {
+                resolved.push(match);
+            }
+        }
+        return resolved;
+    }
+    /**
+     * Builds the message appended to `conversationMessages` when skill(s) activate — this is what
+     * actually puts each skill's `Instructions` into effect for the rest of the run. Override to
+     * change formatting (e.g. a more compact representation for a high skill-activation-count agent).
+     *
+     * @protected
+     */
+    buildSkillActivationMessage(skills) {
+        const sections = skills.map(s => `## Skill Activated: ${s.Name}\n\n${s.Instructions}`);
+        return `The following skill(s) have been activated. Their instructions are now in effect ` +
+            `for the remainder of this run:\n\n${sections.join('\n\n')}`;
+    }
+    /**
+     * Enables a skill's bundled Actions and sub-agents by pushing `specific`-scoped `add` entries
+     * (targeted at exactly the activating agent's ID) onto `params.actionChanges` /
+     * `params.subAgentChanges`. `specific`/`[agent.ID]` is the correct scope for "apply to THIS
+     * agent, at whatever depth it runs, and never leak to its sub-agents":
+     *   - {@link doesChangeScopeApply} returns true only when the running agent's ID is in the list,
+     *     so it applies to the activating agent regardless of depth (a sub-agent that activates a
+     *     skill still gets its tools — which a `root`-scoped change would NOT do, since `root` means
+     *     "the depth-0 agent," not "the current agent").
+     *   - {@link filterActionChangesForSubAgent} / {@link filterSubAgentChangesForSubAgent} propagate
+     *     `specific` as-is, and each downstream agent checks `includes(itsOwnID)` → false, so the
+     *     grant never cascades to sub-agents the activating agent later delegates to.
+     * Because `params` is the same object reference used for the rest of this run, every subsequent
+     * turn's `gatherPromptTemplateData()` call picks up the change automatically — no extra plumbing.
+     *
+     * Override to change propagation scope (e.g. a subclass that wants skill-granted capabilities
+     * to cascade to sub-agents could push `scope: 'all-subagents'` instead).
+     *
+     * @protected
+     */
+    enableSkillCapabilities(skill, params) {
+        const activatingAgentIds = [params.agent.ID];
+        const actionIds = AIEngine.Instance.GetSkillActionIDs(skill.ID);
+        if (actionIds.length > 0) {
+            if (!params.actionChanges) {
+                params.actionChanges = [];
+            }
+            params.actionChanges.push({
+                scope: 'specific',
+                mode: 'add',
+                actionIds,
+                agentIds: activatingAgentIds
+            });
+        }
+        const subAgentIds = AIEngine.Instance.GetSkillSubAgentIDs(skill.ID);
+        if (subAgentIds.length > 0) {
+            if (!params.subAgentChanges) {
+                params.subAgentChanges = [];
+            }
+            params.subAgentChanges.push({
+                scope: 'specific',
+                mode: 'add',
+                subAgentIds,
+                agentIds: activatingAgentIds
+            });
+        }
+    }
+    /**
+     * Creates and immediately finalizes the `AIAgentRunStep` (StepType='Skill') that records this
+     * skill activation for observability/audit. Activation is not itself a failure mode today — it
+     * always finalizes as successful — but subclasses can override to add richer InputData/OutputData
+     * or to make activation conditionally fail (e.g. a licensing check).
+     *
+     * @protected
+     */
+    async recordSkillActivationStep(skill, currentPayload, params) {
+        const stepEntity = await this.createStepEntity({
+            stepType: 'Skill',
+            stepName: `Skill: ${skill.Name}`,
+            targetId: skill.ID,
+            inputData: { skillName: skill.Name },
+            contextUser: params.contextUser,
+            payloadAtStart: currentPayload,
+            payloadAtEnd: currentPayload
+        });
+        await this.finalizeStepEntity(stepEntity, true, undefined, {
+            skillId: skill.ID,
+            skillName: skill.Name
+        });
+    }
+    /**
+     * Executes a 'Plan' next step (Plan Mode): records a `Plan` run-step, raises the standard
+     * `MJ: AI Agent Requests` HITL request with an editable plan-approval `AgentResponseForm`, and
+     * terminates this run awaiting the human's response — reusing the exact same pause/resume
+     * infrastructure `executeChatStep` uses (`createFeedbackRequest` + the existing
+     * `MJAIAgentRequestEntityServer.Save()` auto-resume-on-status-change hook). A rejected or
+     * edited-and-resubmitted plan resumes as a new linked run via the normal run-chain mechanism;
+     * `resolvePlanModeGate` re-checks approval on that new run so a rejection sends the agent back
+     * to present a revised plan rather than through to execution.
+     *
+     * **Important**: the RETURNED `BaseAgentNextStep.step` is `'Chat'`, not `'Plan'` — 'Plan' is
+     * only ever an intermediate classification (used for the `AIAgentRunStep.StepType` audit
+     * record, which the UI reads to render a plan-approval card instead of a generic chat bubble).
+     * The step returned to the framework must stay within `AIAgentRun.FinalStep`'s DB-CHECK-
+     * constrained, terminal-only vocabulary — `'Plan'` is deliberately not part of it (see the
+     * `BaseAgentNextStep.step` doc comment) — so a plan-approval pause is represented as the same
+     * terminal shape `executeChatStep` already uses.
+     *
+     * @protected
+     */
+    async executePlanStep(params, previousDecision) {
+        const planText = previousDecision.planDetails?.plan ?? '';
+        const stepEntity = await this.createStepEntity({
+            stepType: 'Plan',
+            stepName: 'Plan Presented for Approval',
+            contextUser: params.contextUser,
+            inputData: { plan: planText }
+        });
+        await this.finalizeStepEntity(stepEntity, true, undefined, { plan: planText });
+        const responseForm = this.buildPlanApprovalForm(planText);
+        const planPresentation = {
+            step: 'Plan',
+            terminate: true,
+            message: previousDecision.message || 'Please review the proposed plan before I proceed.',
+            reasoning: previousDecision.reasoning,
+            confidence: previousDecision.confidence,
+            responseForm
+        };
+        // For root agents, create a persistent AIAgentRequest so the request is tracked in the
+        // dashboard and can be responded to outside a conversation (mirrors executeChatStep).
+        if (this._depth === 0) {
+            await this.createFeedbackRequest(params, stepEntity, planPresentation);
+        }
+        return {
+            step: 'Chat',
+            terminate: true,
+            message: planPresentation.message,
+            reasoning: previousDecision.reasoning,
+            confidence: previousDecision.confidence,
+            previousPayload: previousDecision.previousPayload,
+            newPayload: previousDecision.newPayload || previousDecision.previousPayload,
+            responseForm
+        };
+    }
+    /**
+     * Builds the editable plan-approval `AgentResponseForm`: the Markdown-rendered plan (with an
+     * Edit toggle so the human can amend it before approving), an optional feedback field that
+     * travels back to the agent with the decision (most useful on Reject — it steers the re-plan),
+     * and an Approve/Reject button group. Override to change the card's layout (e.g. split the
+     * plan into per-step checkboxes instead of one field).
+     *
+     * Approval is a HIGHER-ORDER signal, not just a form reply: conversation hosts detect
+     * `decision === 'approve'` on this form and switch the conversation out of Plan Mode
+     * (see ng-conversations' plan-decision handling), so the follow-up run executes the approved
+     * plan instead of planning again. Rejection keeps Plan Mode on — the agent re-plans with the
+     * feedback in context.
+     *
+     * @protected
+     */
+    buildPlanApprovalForm(planText) {
+        return {
+            title: 'Review Plan',
+            description: 'Review the proposed plan below. Edit it if needed, then approve to proceed — or reject (with a note on what to change) and the agent will re-plan.',
+            submitLabel: 'Submit',
+            questions: [
+                {
+                    id: 'plan',
+                    label: 'Plan',
+                    // markdown: agents author plans in Markdown (see the plan-mode prompt
+                    // instructions); the UI renders a formatted preview with an Edit toggle.
+                    type: { type: 'textarea', markdown: true },
+                    defaultValue: planText,
+                    required: true
+                },
+                {
+                    id: 'reason',
+                    label: 'Feedback',
+                    type: { type: 'textarea', placeholder: 'Optional — if rejecting, tell the agent what to change and it will re-plan.' },
+                    required: false
+                },
+                {
+                    id: 'decision',
+                    label: 'Decision',
+                    type: {
+                        type: 'buttongroup',
+                        options: [
+                            { value: 'approve', label: 'Approve' },
+                            { value: 'reject', label: 'Reject' }
+                        ]
+                    },
+                    required: true
+                }
+            ]
+        };
+    }
     async executeChatStep(params, previousDecision) {
         const stepEntity = await this.createStepEntity({ stepType: 'Chat', stepName: 'User Interaction', contextUser: params.contextUser });
         // Chat steps are successful - they indicate a need for user interaction
@@ -9302,6 +10203,13 @@ The context is now within limits. Please retry your request with the recovered c
     async pruneAndCompactExpiredMessages(params, currentTurn) {
         const messagesToCompact = [];
         const messagesToRemove = [];
+        // Cache-aware guard: confine pruning/compaction to the volatile tail so we don't
+        // perturb the provider's KV-cached prompt prefix. The stable prefix is the maximal
+        // contiguous leading run of non-result messages (system/RAG context, injected
+        // memory, the original user request). Expired messages that fall inside that prefix
+        // are deferred — genuine context overflow still reaches them via attemptContextRecovery.
+        // token optimization via @memberjunction/context-crush (CacheAligner-inspired)
+        const { Boundary: stablePrefixBoundary } = PartitionStablePrefix(params.conversationMessages, (msg) => !this.IsVolatileResultMessage(msg));
         // Phase 1: Identify expired messages
         for (let i = 0; i < params.conversationMessages.length; i++) {
             const msg = params.conversationMessages[i];
@@ -9318,6 +10226,12 @@ The context is now within limits. Please retry your request with the recovered c
             const turnsAlive = currentTurn - turnAdded;
             // Check if expired
             if (turnsAlive > msg.metadata.expirationTurns) {
+                // Defer expiry of messages inside the cache-stable prefix to preserve the
+                // provider's cached prompt prefix; overflow recovery handles them if needed.
+                if (i < stablePrefixBoundary) {
+                    this.logStatus(`[Turn ${currentTurn}] Deferred expiry of cache-stable prefix message at index ${i}`, true, params);
+                    continue;
+                }
                 msg.metadata.isExpired = true;
                 if (msg.metadata.expirationMode === 'Remove') {
                     messagesToRemove.push(i);
@@ -9563,6 +10477,21 @@ The context is now within limits. Please retry your request with the recovered c
             || messageType === 'client-tool-result'
             || messageType === 'tool-result';
     }
+    /**
+     * Returns true if the message is a turn-generated result (action, tool, client tool,
+     * sub-agent, or loop). These are the volatile, expirable messages that accumulate over
+     * turns. Everything else — system/RAG context, injected memory, the original user
+     * request — anchors the cache-stable prompt prefix and is protected from routine pruning.
+     * @protected
+     */
+    IsVolatileResultMessage(msg) {
+        const messageType = msg.metadata?.messageType;
+        return messageType === 'action-result'
+            || messageType === 'client-tool-result'
+            || messageType === 'tool-result'
+            || messageType === 'sub-agent-result'
+            || messageType === 'loop-result';
+    }
     estimateTokens(content, modelName) {
         const text = typeof content === 'string'
             ? content