@memberjunction/ai-agents 5.43.0 → 5.45.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,47 @@ 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 = [];
+        /**
+         * Full observability records for every skill activated this run — one {@link AgentSkillInvocation}
+         * per activation, carrying activation type ('requested' | 'auto'), the provenance-of-authority
+         * gate values that admitted the skill, and the agent-stated reason when self-activated.
+         * Serialized onto `AIAgentRunStep.Skills`: Skill steps record their own activation(s), Prompt
+         * steps record the full set in effect for the turn, and Actions/Sub-Agent steps record the
+         * skill(s) that granted the executed tool (see {@link getSkillAttributionForAction} /
+         * {@link getSkillAttributionForSubAgent}).
+         */
+        this._skillInvocations = [];
+        /**
+         * 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 +278,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 +312,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 +511,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 +1225,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 +1332,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 +1345,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 +1451,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 +1646,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 +1889,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 +2359,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 +2900,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 +2934,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 +2985,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 +3164,118 @@ 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'
+            };
+        }
+        // Plan Mode × skills: agent-initiated activations are only legal BEFORE plan approval,
+        // so the plan the human reviews always reflects the widened tool surface. Once the plan
+        // is approved, a new activation would expand capabilities the reviewer never saw — the
+        // agent must present an updated plan instead (the normal re-plan path).
+        if (this._planModeActive && this._planApproved) {
+            if (nextStep.step !== 'Retry') {
+                this._generalValidationRetryCount++;
+            }
+            return {
+                step: 'Retry',
+                terminate: false,
+                errorMessage: 'Skill activations are not allowed after your plan has been approved — ' +
+                    'the approved plan did not include these capabilities. Present an updated plan ' +
+                    "(nextStep.type='Plan') that includes the skill(s) you need and why, so the user " +
+                    'can review the expanded tool surface.'
+            };
+        }
+        // Agent-initiated (self-)activation is governed by the DOUBLE activation gate: the agent's
+        // SkillActivationMode AND each skill's ActivationMode must both be 'Auto'. RequestedOnly
+        // skills can only enter a run via an explicit user /skill request (requestedSkillIDs) —
+        // never via this step. This is the same set the prompt catalog was built from, so a
+        // well-behaved model can only name skills that pass; the re-check here is the enforcement
+        // boundary against hallucinated or smuggled names.
+        const availableSkills = AIEngine.Instance.GetAutoActivatableSkillsForAgent(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 +4794,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 +4814,16 @@ 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). This is the
+            // SELF-ACTIVATION surface, so it uses the double-gated auto set: empty unless the
+            // agent's SkillActivationMode is 'Auto', and containing only skills whose own
+            // ActivationMode is 'Auto' (RequestedOnly skills never appear — they can only enter
+            // a run via an explicit user /skill request). Also empty for AcceptsSkills='None',
+            // and 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.GetAutoActivatableSkillsForAgent(agent, _contextUser);
+            const skillsCatalog = this.formatSkillsCatalog(availableSkills);
             const contextData = {
                 agentName: agent.Name,
                 agentDescription: agent.Description,
@@ -4394,6 +4833,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 +5368,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 +5454,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 +5685,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 +6002,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 +6128,20 @@ 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;
+        // Stamp the run record so the UX (run-header Plan Mode chip) and plan-drift audits can
+        // tell plan-mode runs apart without re-deriving gate state from steps/requests.
+        if (this._agentRun && planModeGate.active) {
+            this._agentRun.PlanMode = true;
+        }
+        // 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 +6151,66 @@ 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`: this is a root agent (`_depth === 0`) AND either `agent.RequirePlanMode`
+     *   (mandatory HITL — forces plan mode on every root run regardless of the per-request flag;
+     *   `SupportsPlanMode` is irrelevant when set) OR `agent.SupportsPlanMode` (capability,
+     *   default ON/opt-out) AND `params.planMode` (per-request, default OFF). 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 requiredByAgent = params.agent.RequirePlanMode === true;
+        const requestedByCaller = !!(params.agent.SupportsPlanMode && params.planMode === true);
+        const active = this._depth === 0 && (requiredByAgent || requestedByCaller);
+        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.
      *
@@ -5664,9 +6285,25 @@ The context is now within limits. Please retry your request with the recovered c
                 })
                 : undefined
         });
+        // Skill observability: persist the invocation records for this step. Prompt steps
+        // default to everything currently in effect (so every turn's injection is auditable);
+        // other step types only carry skills when the caller attributes them explicitly.
+        const skillsForStep = params.skills
+            ?? (params.stepType === 'Prompt' && this._skillInvocations.length > 0
+                ? this._skillInvocations
+                : undefined);
+        if (skillsForStep && skillsForStep.length > 0) {
+            stepEntity.Skills = JSON.stringify(skillsForStep);
+        }
         // 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 +6578,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':
@@ -6521,7 +7168,7 @@ The context is now within limits. Please retry your request with the recovered c
      * @param parentStepId - Optional ID of parent step (e.g., ForEach/While loop step) for proper UI hierarchy
      * @param subAgentPayloadOverride - Optional payload override for sub-agent execution, if provided the normal payload computation is skipped
      */
-    async executeChildSubAgentStep(params, previousDecision, parentStepId, subAgentPayloadOverride, stepCount = 0) {
+    async executeChildSubAgentStep(params, previousDecision, parentStepId, subAgentPayloadOverride, stepCount = 0, resolvedSubAgentEntity) {
         const subAgentRequest = previousDecision.subAgent;
         // Check for cancellation before starting
         if (params.cancellationToken?.aborted) {
@@ -6557,13 +7204,18 @@ The context is now within limits. Please retry your request with the recovered c
             conversationMessages: params.conversationMessages,
             parentAgentHierarchy: this._agentHierarchy
         };
-        // Get sub-agent entity to access payload paths
-        const subAgentEntity = AIEngine.Instance.Agents.find(a => a.Name === subAgentRequest.name &&
-            UUIDsEqual(a.ParentID, params.agent.ID));
+        // Get sub-agent entity to access payload paths. Prefer the entity the caller already
+        // resolved (resolveSubAgentByName — covers ParentID children AND runtime-granted
+        // sub-agents from skill activations / subAgentChanges); fall back to the ParentID
+        // lookup, then the effective set, for any legacy direct callers of this method.
+        const subAgentEntity = resolvedSubAgentEntity
+            ?? AIEngine.Instance.Agents.find(a => a.Name === subAgentRequest.name &&
+                UUIDsEqual(a.ParentID, params.agent.ID))
+            ?? this.getEffectiveSubAgentsForValidation(params.agent.ID).find(a => a.Name.trim().toLowerCase() === subAgentRequest.name?.trim().toLowerCase());
         if (!subAgentEntity) {
             throw new Error(`Sub-agent '${subAgentRequest.name}' not found`);
         }
-        const stepEntity = await this.createStepEntity({ stepType: 'Sub-Agent', stepName: `Execute Sub-Agent: ${subAgentRequest.name}`, contextUser: params.contextUser, targetId: subAgentEntity.ID, inputData, payloadAtStart: previousDecision.newPayload, parentId: parentStepId });
+        const stepEntity = await this.createStepEntity({ stepType: 'Sub-Agent', stepName: `Execute Sub-Agent: ${subAgentRequest.name}`, contextUser: params.contextUser, targetId: subAgentEntity.ID, inputData, payloadAtStart: previousDecision.newPayload, parentId: parentStepId, skills: this.getSkillAttributionForSubAgent(subAgentEntity, params.agent) });
         // Increment execution count for this sub-agent
         this.incrementExecutionCount(subAgentEntity.ID);
         try {
@@ -6826,16 +7478,24 @@ The context is now within limits. Please retry your request with the recovered c
             return await this.executeRelatedSubAgentStep(params, previousDecision, resolved.subAgentEntity, resolved.relationship, parentStepId, subAgentPayloadOverride, stepCount);
         }
         if (resolved) {
-            return await this.executeChildSubAgentStep(params, previousDecision, parentStepId, subAgentPayloadOverride, stepCount);
-        }
-        this.logError(`Sub-agent '${name}' not found or not active for agent '${params.agent.Name}'`, {
+            return await this.executeChildSubAgentStep(params, previousDecision, parentStepId, subAgentPayloadOverride, stepCount, resolved.subAgentEntity);
+        }
+        // Execution-time resolution failure. Count it against the shared validation-retry cap
+        // (MAX_VALIDATION_RETRIES) so a model that keeps picking an unresolvable sub-agent fails
+        // the run with a clear guardrail message instead of looping forever, and tell the model
+        // exactly which sub-agents ARE available so it can self-correct on the next turn.
+        const availableNames = this.getEffectiveSubAgentsForValidation(params.agent.ID)
+            .map(a => a.Name).join(', ') || '(none)';
+        this.logError(`Sub-agent '${name}' not found or not active for agent '${params.agent.Name}'. Available sub-agents: ${availableNames}`, {
             agent: params.agent,
             category: 'SubAgentExecution'
         });
+        this._generalValidationRetryCount++;
         return {
             step: 'Retry',
             terminate: false,
-            errorMessage: `Sub-agent '${name}' not found or not active`,
+            errorMessage: `Sub-agent '${name}' not found or not active. Available sub-agents: ${availableNames}. ` +
+                `Pick one of the available sub-agents, or complete the task another way — do not request '${name}' again.`,
             previousPayload: previousDecision.newPayload,
             newPayload: previousDecision.newPayload
         };
@@ -6871,6 +7531,16 @@ The context is now within limits. Please retry your request with the recovered c
                 return { subAgentEntity: relatedAgent, relationship: rel };
             }
         }
+        // 3) Runtime-granted sub-agents (skill activation / caller subAgentChanges): resolve from
+        // the SAME effective set the prompt offered and validateSubAgentNextStep approved. Without
+        // this branch, a skill-granted sub-agent passes validation but fails execution ("not found
+        // or not active") — and because the catalog keeps offering it, the model re-picks the same
+        // sub-agent forever (observed live: Research Agent looping 36+ turns on the skill-granted
+        // Infographic Agent). No relationship row exists for these, so they dispatch child-style.
+        const effectiveAgent = this.getEffectiveSubAgentsForValidation(params.agent.ID).find(a => a.Status === 'Active' && a.Name.trim().toLowerCase() === normalized);
+        if (effectiveAgent) {
+            return { subAgentEntity: effectiveAgent };
+        }
         return undefined;
     }
     /**
@@ -7099,6 +7769,7 @@ The context is now within limits. Please retry your request with the recovered c
             stepName: `Execute Parallel Sub-Agent: ${request.name}`,
             contextUser: params.contextUser,
             targetId: subAgentEntity.ID,
+            skills: this.getSkillAttributionForSubAgent(subAgentEntity, params.agent),
             inputData: {
                 agentName: params.agent.Name,
                 subAgentName: request.name,
@@ -7269,7 +7940,8 @@ The context is now within limits. Please retry your request with the recovered c
             targetId: subAgentEntity.ID,
             inputData,
             payloadAtStart: previousDecision.newPayload,
-            parentId: parentStepId
+            parentId: parentStepId,
+            skills: this.getSkillAttributionForSubAgent(subAgentEntity, params.agent)
         });
         // Increment execution count for this sub-agent
         this.incrementExecutionCount(subAgentEntity.ID);
@@ -7778,7 +8450,7 @@ The context is now within limits. Please retry your request with the recovered c
                     actionName: aa.name,
                     actionParams: aa.params
                 };
-                const stepEntity = await this.createStepEntity({ stepType: 'Actions', stepName: `Execute Action: ${aa.name}`, contextUser: params.contextUser, targetId: actionEntity.ID, inputData: actionInputData, payloadAtStart: currentPayload, payloadAtEnd: currentPayload, parentId: parentStepId });
+                const stepEntity = await this.createStepEntity({ stepType: 'Actions', stepName: `Execute Action: ${aa.name}`, contextUser: params.contextUser, targetId: actionEntity.ID, inputData: actionInputData, payloadAtStart: currentPayload, payloadAtEnd: currentPayload, parentId: parentStepId, skills: this.getSkillAttributionForAction(actionEntity.ID, params.agent) });
                 lastStep = stepEntity;
                 // Override step number to ensure unique values for parallel actions
                 stepEntity.StepNumber = baseStepNumber + numActionsProcessed++;
@@ -8097,6 +8769,432 @@ 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) {
+            // Agent self-activation — carry the model's stated rationale (skillActivations[].reason)
+            // into the provenance record. Names were fuzzy-corrected in validateSkillNextStep, so a
+            // case-insensitive exact match against the request list is reliable here.
+            const request = requested.find(r => r.name.trim().toLowerCase() === skill.Name.trim().toLowerCase());
+            const invocation = this.buildSkillInvocation(skill, params.agent, 'auto', request?.reason);
+            await this.recordSkillActivationStep(skill, currentPayload, params, invocation);
+            this.enableSkillCapabilities(skill, params);
+            this._activatedSkillIDs.push(skill.ID);
+            this._skillInvocations.push(invocation);
+        }
+        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 droppedIds = requestedIds.filter(id => !allowed.some(s => UUIDsEqual(id, s.ID)));
+        if (droppedIds.length > 0) {
+            this.notifyDroppedSkillRequests(droppedIds, params);
+        }
+        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) {
+            const invocation = this.buildSkillInvocation(skill, params.agent, 'requested');
+            await this.recordSkillActivationStep(skill, currentPayload, params, invocation);
+            this.enableSkillCapabilities(skill, params);
+            this._activatedSkillIDs.push(skill.ID);
+            this._skillInvocations.push(invocation);
+        }
+        const activationMessage = this.buildSkillActivationMessage(newlyActivated);
+        if (!params.conversationMessages) {
+            params.conversationMessages = [];
+        }
+        params.conversationMessages.push({
+            role: 'user',
+            content: activationMessage,
+            metadata: {
+                turnAdded: this._promptTurnCount,
+                messageType: 'skill-activation'
+            }
+        });
+    }
+    /**
+     * Handles user-requested skill IDs that failed the activation guard (agent-accepted ∩
+     * user-permitted). A silent drop leaves both the user AND the agent blind to the refusal —
+     * the agent then improvises around the missing capability instead of explaining it. This
+     * emits a server-side warning log and injects a system note into the conversation so the
+     * agent tells the user why the skill isn't available rather than working around it.
+     *
+     * @protected
+     */
+    notifyDroppedSkillRequests(droppedIds, params) {
+        const names = droppedIds.map(id => AIEngine.Instance.Skills.find(s => UUIDsEqual(s.ID, id))?.Name ?? id);
+        const reason = params.agent.AcceptsSkills === 'None'
+            ? `agent '${params.agent.Name}' does not accept skills (AcceptsSkills='None')`
+            : `the skill(s) are not available to agent '${params.agent.Name}' — not Active, not assigned to it (AcceptsSkills='Limited'), or the user lacks Run permission`;
+        LogErrorEx({
+            message: `Requested skill activation dropped for [${names.join(', ')}]: ${reason}`,
+            severity: 'warning',
+            category: 'AgentSkills'
+        });
+        if (!params.conversationMessages) {
+            params.conversationMessages = [];
+        }
+        params.conversationMessages.push({
+            role: 'user',
+            content: `SYSTEM NOTE: The user requested activation of the following skill(s) for this run: ${names.join(', ')}. The request was NOT honored because ${reason}. Briefly inform the user that the requested skill(s) are not available to you and, if appropriate, suggest an agent that accepts skills or that an administrator can grant this capability. Do NOT attempt to build, delegate, or improvise a workaround for the missing capability.`,
+            metadata: {
+                turnAdded: this._promptTurnCount,
+                messageType: 'skill-activation-refused'
+            }
+        });
+    }
+    /**
+     * 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) {
+        // Agent-initiated activations resolve against the double-gated AUTO set only —
+        // RequestedOnly skills (on either side of the gate) can never be self-activated, even if
+        // a response somehow names one that validateSkillNextStep didn't catch.
+        const availableSkills = AIEngine.Instance.GetAutoActivatableSkillsForAgent(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
+            });
+        }
+    }
+    /**
+     * Builds the {@link AgentSkillInvocation} observability record for a skill activation —
+     * capturing WHO pulled the trigger and the provenance-of-authority gate values in effect at
+     * activation time, so auditors can see exactly which configuration admitted the skill even
+     * if that configuration later changes.
+     *
+     * @protected
+     */
+    buildSkillInvocation(skill, agent, activationType, reason) {
+        return {
+            SkillID: skill.ID,
+            SkillName: skill.Name,
+            ActivationType: activationType,
+            Provenance: {
+                AgentAcceptsSkills: agent.AcceptsSkills,
+                SkillActivationMode: skill.ActivationMode,
+                AgentSkillActivationMode: agent.SkillActivationMode,
+                RequestedBy: activationType === 'requested' ? 'user-request' : 'agent-decision'
+            },
+            ...(reason ? { Reason: reason } : {})
+        };
+    }
+    /**
+     * Resolves which activated skill(s), if any, granted the given action to this agent — the
+     * attribution recorded on the Actions step's `Skills` column. Returns `undefined` (no
+     * linkage) when the action is one of the agent's NATIVE grants (an Active `MJ: AI Agent
+     * Actions` row), even if an activated skill also bundles it: native authority takes
+     * precedence, and `Skills = NULL` is the contract for "the agent had this tool anyway".
+     *
+     * @protected
+     */
+    getSkillAttributionForAction(actionId, agent) {
+        if (this._skillInvocations.length === 0 || !actionId) {
+            return undefined;
+        }
+        const isNative = AIEngine.Instance.AgentActions.some(aa => UUIDsEqual(aa.AgentID, agent.ID) && UUIDsEqual(aa.ActionID, actionId) && aa.Status === 'Active');
+        if (isNative) {
+            return undefined;
+        }
+        const granting = this._skillInvocations.filter(inv => AIEngine.Instance.GetSkillActionIDs(inv.SkillID).some(id => UUIDsEqual(id, actionId)));
+        return granting.length > 0 ? granting : undefined;
+    }
+    /**
+     * Resolves which activated skill(s), if any, granted the given sub-agent to this agent — the
+     * attribution recorded on the Sub-Agent step's `Skills` column. Returns `undefined` when the
+     * sub-agent is a NATIVE relationship (a `ParentID` child of this agent, or an Active
+     * `MJ: AI Agent Relationships` referenced-sub-agent row), even if an activated skill also
+     * bundles it — same native-precedence contract as {@link getSkillAttributionForAction}.
+     *
+     * @protected
+     */
+    getSkillAttributionForSubAgent(subAgent, agent) {
+        if (this._skillInvocations.length === 0 || !subAgent) {
+            return undefined;
+        }
+        const isParentChild = subAgent.ParentID != null && UUIDsEqual(subAgent.ParentID, agent.ID);
+        const isReferenced = AIEngine.Instance.AgentRelationships.some(rel => UUIDsEqual(rel.AgentID, agent.ID) && UUIDsEqual(rel.SubAgentID, subAgent.ID) && rel.Status === 'Active');
+        if (isParentChild || isReferenced) {
+            return undefined;
+        }
+        const granting = this._skillInvocations.filter(inv => AIEngine.Instance.GetSkillSubAgentIDs(inv.SkillID).some(id => UUIDsEqual(id, subAgent.ID)));
+        return granting.length > 0 ? granting : undefined;
+    }
+    /**
+     * Creates and immediately finalizes the `AIAgentRunStep` (StepType='Skill') that records this
+     * skill activation for observability/audit. The step's `Skills` column carries the single
+     * {@link AgentSkillInvocation} performed (activation type, provenance of authority, and the
+     * agent-stated reason when self-activated). 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, invocation) {
+        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,
+            ...(invocation ? { skills: [invocation] } : {})
+        });
+        await this.finalizeStepEntity(stepEntity, true, undefined, {
+            skillId: skill.ID,
+            skillName: skill.Name,
+            ...(invocation ? {
+                activationType: invocation.ActivationType,
+                requestedBy: invocation.Provenance.RequestedBy,
+                ...(invocation.Reason ? { reason: invocation.Reason } : {})
+            } : {})
+        });
+    }
+    /**
+     * 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 +10400,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 +10423,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 +10674,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