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

package/dist/base-agent.d.ts

@@ -14,21 +14,24 @@ import { MJAIAgentTypeEntity, MJTemplateParamEntity, MJAIAgentRelationshipEntity
 import { type NativeToolBinding } from './native-tools/control-tools.js';
 import { MJAIAgentRunEntityExtended, MJAIAgentRunStepEntityExtended, MJAIPromptEntityExtended, MJAIAgentEntityExtended, MJAIModelEntityExtended, MJAIPromptRunEntityExtended } from "@memberjunction/ai-core-plus";
 import { UserInfo, IMetadataProvider } from '@memberjunction/core';
-import { ChatMessage, ChatMessageContent, BaseRealtimeModel, IRealtimeSession, ChatToolChoice } from '@memberjunction/ai';
+import { AIDecisionRunResult } from '@memberjunction/ai-prompts';
+import { ChatMessage, ChatMessageContent, BaseRealtimeModel, IRealtimeSession, ChatToolChoice, DecisionAnswer } from '@memberjunction/ai';
 import { BaseAgentType } from './agent-types/base-agent-type.js';
 import { type CodeLang } from '@memberjunction/context-crush/code';
 import { RealtimeSessionRunnerDeps } from './realtime/realtime-session-runner.js';
 import { RealtimeCoAgentConfig } from './realtime/realtime-coagent-config.js';
 import { AIEngine } from '@memberjunction/aiengine';
+import { AgentMemoryObservability } from './agent-memory-context-builder.js';
 import { CompactionOutcome, EffectiveContextBudget } from './ConversationCompactionManager.js';
 import { ConversationToolCall, ConversationToolExecutionResult, ConversationToolSummaryHost } from './ConversationToolManager.js';
 import { CarryForwardStepRecord } from './tool-result-format.js';
 import { AgentPreExecutionRAGResult } from './agent-pre-execution-rag.js';
-import { AIPromptParams, AIPromptRunResult, ExecuteAgentParams, AgentConfiguration, ExecuteAgentResult, AgentAction, AgentSubAgentRequest, BaseAgentNextStep, MessageLifecycleEvent, AgentChatMessage, AgentChatMessageMetadata, AIModelSelectionInfo, ActionChange, ActionChangeScope, SubAgentChange, MediaOutput, FileOutputRef, SecondaryScopeConfig, SecondaryScopeValue, AgentResponseForm, AgentPipelineRequest, AgentSkillActivationRequest, AgentSkillInvocation, SkillAvailabilityPurpose } from '@memberjunction/ai-core-plus';
+import { AIPromptParams, AIPromptRunResult, ExecuteAgentParams, AgentConfiguration, ExecuteAgentResult, AgentAction, AgentSubAgentRequest, BaseAgentNextStep, MessageLifecycleEvent, AgentChatMessage, AgentChatMessageMetadata, AIModelSelectionInfo, ActionChange, ActionChangeScope, SubAgentChange, MediaOutput, FileOutputRef, SecondaryScopeConfig, SecondaryScopeValue, AgentResponseForm, AgentPipelineRequest, AgentSkillActivationRequest, AgentSkillInvocation, SkillAvailabilityPurpose, AgentDecisionRequest, AgentDecisionResult, AgentDecisionAnswerSummary } from '@memberjunction/ai-core-plus';
 import { MJActionEntityExtended, ActionResult, ActionParam, AIDirective } from '@memberjunction/actions-base';
 import { RuntimeStateDateTime, RuntimeStateScratchpad } from './runtime-state-fragment.js';
 import { ArtifactToolCall, StoredToolResult } from './ArtifactToolManager.js';
 import { MemoryWriteRequest, MemoryWriteResult } from './MemoryWriteManager.js';
+import { AgentDecisionService } from './AgentDecisionService.js';
 import { PipelineToolRegistry, PipelineExecutionResult } from './pipeline/index.js';
 /**
  * Compact representation of a single action's execution result, used for
@@ -123,6 +126,12 @@ interface AgentBaseCatalog {
     /** Agent-type prompt params merged from schema defaults + agent config (NO runtime overrides). */
     baseAgentTypePromptParams: Record<string, unknown>;
 }
+/**
+ * Turns one decision call's typed answers into what its reader gets. A loop turn's model reads
+ * `AgentDecisionService.SummarizeAnswers`; an agent type that routes on the answers reads
+ * `SummarizeDecisionAnswers`, which keeps each distribution.
+ */
+type DecisionAnswerSummarizer = (answers: Record<string, DecisionAnswer>) => Record<string, AgentDecisionAnswerSummary>;
 export declare class BaseAgent {
     /**
      * Maximum allowed validation retries before forcing failure.
@@ -649,6 +658,10 @@ export declare class BaseAgent {
      * Allows agents to explore input artifacts on demand.
      */
     private _artifactToolManager;
+    /**
+     * Service for evaluating agent decisions inline via fast decision models.
+     */
+    protected _agentDecisionService: AgentDecisionService;
     /**
      * Reverse map from sanitized tool name back to Action, for the turn currently being prepared.
      *
@@ -685,6 +698,47 @@ export declare class BaseAgent {
      * @private
      */
     private _effectiveSubAgents;
+    /**
+     * The merged agent-type prompt params of the current step. Populated during
+     * gatherPromptTemplateData() and read by the finishIf gate, which runs in executeActionsStep()
+     * and executeNextStep() after the prompt that requested the step.
+     * @private
+     */
+    private _agentTypePromptParams;
+    /**
+     * The run's catalog narrowing (plan Task 3.7): what the prompt hides from its action, sub-agent
+     * and skill lists. Computed once, on the run's first prompt, and reused by every later step, so
+     * the catalog the model sees never changes mid-run. `undefined` until then; hides nothing when
+     * narrowing is off or failed open.
+     * @private
+     */
+    private _catalogNarrowing;
+    /**
+     * The request that opened the run: the last user message when it started, before the framework
+     * added anything. Catalog narrowing judges the catalog against it.
+     * @private
+     */
+    private _openingRequest;
+    /**
+     * The run's {@link AIPromptExecutionScope}, recorded when the run starts, for decision calls made
+     * from helpers that are not handed the run's params (discovery, catalog narrowing).
+     * @private
+     */
+    private _runExecutionScope;
+    /**
+     * Whether the run answers its conversation's opening request ({@link IsOpeningTurn}), read from
+     * the messages it started with. Decision discovery asks about no other turn.
+     * @private
+     */
+    private _isOpeningTurn;
+    /** The longest the catalog narrowing decision may take before the run shows the full catalog. */
+    private static readonly CATALOG_NARROWING_TIMEOUT_MS;
+    /**
+     * Decision requests held back by the prompt that made them, because the step that carried them
+     * can end the run. They run before the next prompt, or are skipped when the run ends first.
+     * @private
+     */
+    private _heldDecisions;
     /**
      * 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
@@ -1321,6 +1375,16 @@ export declare class BaseAgent {
      * @returns A human-readable scope label
      */
     private determineNoteScope;
+    /**
+     * The observability context memory injection runs under for an agent run: the run's ID, the next
+     * step number, and a callback that adds each rerank step to the run's steps. A rerank step carries
+     * the rerank's prompt run, whose cost and token rollups include a prompt-backed reranker's own
+     * prompt runs, so the run's totals and its `MaxCostPerRun` / `MaxTokensPerRun` guardrails count
+     * them. Undefined when there is no run.
+     *
+     * @param run - The current agent run, or null before one exists
+     */
+    protected MemoryObservability(run: MJAIAgentRunEntityExtended | null): AgentMemoryObservability | undefined;
     /**
      * Inject notes and examples into agent context memory.
      * Called automatically before agent execution if injection is enabled on the agent.
@@ -1378,6 +1442,98 @@ export declare class BaseAgent {
      * @returns The structured RAG result, or `null` if no scopes produced results.
      */
     protected InjectPreExecutionRAG(lastUserMessage: string, agent: MJAIAgentEntityExtended, contextUser: UserInfo | undefined, conversationMessages: ChatMessage[] | undefined, originalMessages: ChatMessage[] | undefined, primaryScopeEntityId?: string, primaryScopeRecordId?: string, secondaryScopes?: Record<string, SecondaryScopeValue>, payload?: unknown): Promise<AgentPreExecutionRAGResult | null>;
+    /**
+     * Decision discovery (plan Task 3.1): suggests the agent to delegate to before the first prompt.
+     *
+     * Runs in parallel with the rest of Phase 2 of `Execute()`, and only when the merged agent-type
+     * prompt params set `decisionsEnabled: true` (the master switch, {@link DecisionsEnabled}) and
+     * `decisionDiscovery: true`, the run answers its conversation's opening request
+     * ({@link IsOpeningTurn}), and that request @mentions no agent. A follow-up turn is never asked
+     * about: it may be continuing work with an agent already engaged, and a suggestion must not pull
+     * the agent away from it. One decision asks which of the agents the user may run (and the host
+     * allows) should handle the request, and whether a specialist should. When both answers are
+     * confident, a `<suggested_agent>` system message is unshifted onto `conversationMessages`, the
+     * way pre-execution RAG adds `<retrieved_context>`. Each discovery is recorded as one
+     * `Agent discovery` Decision step.
+     *
+     * Fails safe: an error, a timeout, a cancelled run, an unusable answer or an unsure one adds
+     * nothing, so the agent behaves as it would without discovery. So do fewer than
+     * {@link DECISION_DISCOVERY_MIN_OPTIONS} options. Never delays the first prompt by more than
+     * {@link DECISION_DISCOVERY_TIMEOUT_MS}, and never throws.
+     *
+     * The any-applies question does not name the options, so the decision cannot say that none of
+     * them fits: see {@link DECISION_DISCOVERY_APPLIES_INSTRUCTIONS} for why it stays that way for now.
+     *
+     * @param agent - The agent being executed.
+     * @param contextUser - The user whose run permission decides the options.
+     * @param conversationMessages - The mutated message array that flows to the LLM (the suggestion is unshifted here).
+     * @param data - The run's `ExecuteAgentParams.data`. Its `__agentTypePromptParams` overrides the agent's prompt
+     *   params, and its `ALL_AVAILABLE_AGENTS`, when an array, is the host's allow-list: no other agent is suggested.
+     */
+    protected InjectDecisionDiscovery(agent: MJAIAgentEntityExtended, contextUser: UserInfo | undefined, conversationMessages: ChatMessage[] | undefined, data: Record<string, unknown> | undefined): Promise<void>;
+    /**
+     * Whether discovery is on for this run: the master switch ({@link DecisionsEnabled}) and
+     * `decisionDiscovery` are both on. Read without rebuilding the merged prompt params, since it is
+     * asked on every run of every agent: each setting from the per-run override when it sets one,
+     * otherwise from the agent's base params, cached on AIEngine with its base catalog. Only a cold
+     * cache builds them.
+     */
+    private isDecisionDiscoveryOnFor;
+    /**
+     * The run's merged agent-type prompt params (schema defaults < agent < per-run overrides), once
+     * discovery is on: the cached base params when there is no override, otherwise built.
+     */
+    private decisionDiscoveryPromptParams;
+    /** The agent's base prompt params (no per-run overrides), from the base catalog AIEngine caches, when it holds one. */
+    private cachedBasePromptParams;
+    /** Builds the merged prompt params, as `gatherPromptTemplateData` does. */
+    private buildDecisionDiscoveryPromptParams;
+    /**
+     * Records one `Agent discovery` step around a bounded discovery, and returns what it found. A
+     * failed discovery is logged as a warning; an unsure one only in verbose logs, except that an
+     * answer from a model with no discovery calibration is warned about once per model, because
+     * then discovery can never suggest anything.
+     */
+    private runDecisionDiscovery;
+    /** The answering models already warned about as having no discovery calibration, so each is warned about once per process. */
+    private static readonly _uncalibratedDiscoveryModelsWarned;
+    /**
+     * Warns, once per model, that discovery answered by a model with no discovery calibration
+     * suggests nothing. That happens when a decision model is added or renamed, when a vendor model
+     * moves to another version (Jev's `APIName`), or when LLM Decision answers through a chat model
+     * other than the one its calibration was fitted on; without the warning the only trace is each
+     * `Agent discovery` step's reason.
+     */
+    private static warnUncalibratedDiscoveryModel;
+    /**
+     * Runs `discover` until it finishes, {@link DECISION_DISCOVERY_TIMEOUT_MS} passes, or the run is
+     * cancelled. A timeout or a cancellation aborts the signal `discover` was given, which aborts the
+     * decision call, and returns a failed discovery at once. What `discover` returns after that
+     * suggests nothing, but the prompt run of its decision call is still linked to `step` once it
+     * settles ({@link linkLateDecisionPromptRun}), so the run counts the call's cost.
+     */
+    private boundDecisionDiscovery;
+    /**
+     * The discovery itself: the options, rebuilt from the permitted catalog, then one decision about
+     * the opening request, and what its answer means. Never throws.
+     */
+    private discoverAgent;
+    /**
+     * The Choice's options, rebuilt on every call and never cached ({@link BuildDecisionDiscoveryOptionSet}):
+     * from AIEngine's current catalog, the agents the user may run, the decision prompt's option cap,
+     * and the semantic search over the opening request when the provider can run it.
+     */
+    private decisionDiscoveryOptionSet;
+    /** Opens the `Agent discovery` Decision step. Without a run there is no step. */
+    private startDecisionDiscoveryStep;
+    /**
+     * Finalizes the `Agent discovery` step: the answer, whether it was injected, the host allow-list,
+     * the agents left out for having no description (at most {@link DECISION_DISCOVERY_MAX_RECORDED_IDS}
+     * IDs), any narrowing, and the call's usage.
+     */
+    private finishDecisionDiscoveryStep;
+    /** Logs that decision discovery failed, so nothing was suggested. */
+    private warnDecisionDiscovery;
     /**
      * Converts UI markup (@{...} syntax) in user messages to plain text.
      * This prevents agents from being confused by UI-specific JSON syntax and reduces token usage.
@@ -1518,15 +1674,22 @@ export declare class BaseAgent {
     /**
      * The `tool_choice` for this turn (§8.3).
      *
-     * `'auto'` normally, `'none'` on the last turn this run will be allowed.
+     * `'auto'` normally; on the last turn this run will be allowed, a forced `complete_task` call.
      *
      * **Why the final turn is special.** A tool call is a request to continue: the framework runs
      * the action, feeds the result back, and the model decides again. On the last permitted
      * iteration there is no "again" — the limit check fires the moment the turn returns, so the
      * action is executed, paid for, and its result discarded, and the run ends with no answer for
      * the user because the model spent its last turn asking a question instead of answering one.
-     * Forcing `'none'` converts that turn into what the framework actually needs from it: a
-     * terminal envelope.
+     * The final turn is forced to what the framework actually needs from it: a terminal answer.
+     *
+     * **Why `complete_task` and not `'none'`.** Under implicit control flow, `'none'` forbids the
+     * model's only way to store its result — `payload_change_request` and `complete_task` are tools
+     * too — so a forced `'none'` turn can end the run but never deliver the payload. Naming
+     * `complete_task` forces the one call that does both. A model that is NOT on implicit control
+     * flow never receives `complete_task` (the runner strips control tools), and the runner then
+     * downgrades the named choice to `'none'`: the envelope turn the hybrid needs. Providers also
+     * enforce a named choice more reliably than `'none'`.
      *
      * **What this does NOT fix.** Models call a tool on a measurable share of turns whose right
      * answer was chat, completion or delegation. Those are not predictable
@@ -1534,11 +1697,11 @@ export declare class BaseAgent {
      * address them. That belongs to the prompt, and is why the native-mode Actions section names
      * the cases explicitly.
      *
-     * Subclasses may narrow this further; the base contract is that a forced `'none'` must never be
-     * relaxed to `'auto'` on a turn the framework has already decided is terminal.
+     * Subclasses may narrow this further; the base contract is that a forced terminal choice must
+     * never be relaxed to `'auto'` on a turn the framework has already decided is terminal.
      *
      * @param params The run parameters, for the per-run iteration override
-     * @returns `'none'` on the final permitted iteration, otherwise `'auto'`
+     * @returns `{ name: 'complete_task' }` on the final permitted iteration, otherwise `'auto'`
      */
     protected resolveToolChoiceForTurn(params: ExecuteAgentParams): ChatToolChoice;
     /**
@@ -1861,6 +2024,11 @@ export declare class BaseAgent {
      * @returns Modified next step if guardrails exceeded, or original next step
      * @protected
      */
+    private _selfCheckAttemptsByRun;
+    private _selfCheckLinkByAgent;
+    private applySelfCheck;
+    /** Runs the self-check when a success exit did not pass through the guardrail hook. */
+    private selfCheckSuccess;
     protected checkExecutionGuardrails<P>(params: ExecuteAgentParams, nextStep: BaseAgentNextStep<P>, currentPayload: P, agentRun: MJAIAgentRunEntityExtended, currentStep: MJAIAgentRunStepEntityExtended): Promise<BaseAgentNextStep<P>>;
     /**
      * Checks if any agent run guardrails have been exceeded.
@@ -2053,6 +2221,8 @@ export declare class BaseAgent {
      * @protected
      */
     protected processNextStep<P>(nextStep: BaseAgentNextStep<P>, params: ExecuteAgentParams, agentType: MJAIAgentTypeEntity, promptResult: AIPromptRunResult, currentPayload: P, currentStep: MJAIAgentRunStepEntityExtended): Promise<BaseAgentNextStep<P>>;
+    /** The tool name the model used for a call on this turn — `payload_change_request` when it cannot be found. */
+    private nativeToolNameForCall;
     /**
      * Executes a batch of artifact tool calls, recording each as its own
      * `Tool` AIAgentRunStep (a sibling of the Prompt step that requested them)
@@ -2303,6 +2473,171 @@ export declare class BaseAgent {
      * @protected
      */
     protected injectPipelineResultMessage(params: ExecuteAgentParams, result: PipelineExecutionResult): void;
+    /** At most this many decision calls run at once for one agent turn. */
+    private static readonly DECISION_CONCURRENCY;
+    /**
+     * Runs `fn` over `items` with at most `limit` calls in flight, keeping results in input order.
+     * One call's failure never rejects the others: a call that throws is settled with `onError`'s
+     * result in its place.
+     */
+    private runWithConcurrencyLimit;
+    /**
+     * Answers the decision requests from one agent turn, each logged as an `AIAgentRunStep`
+     * (StepType 'Decision'), with bounded concurrency. A failed request never fails the run: it
+     * becomes that request's `success: false`, which the agent reads on its next turn.
+     *
+     * Two limits bound the turn. At most `decisionsMaxRequests` requests run (default
+     * {@link MAX_DECISION_REQUESTS_PER_TURN}); each request over that cap is not run and records no
+     * step, and its result says why. And the requests make at most `decisionsMaxCallsPerTurn`
+     * decision calls in total, counting every `forEachItemIn` item (default
+     * {@link MAX_DECISION_CALLS_PER_TURN}). That budget is handed out in request order before any
+     * call is made, so which calls run never depends on timing. A `forEachItemIn` request it cuts
+     * short asks its first items and reports the rest in `skippedCount`. A request it leaves no calls
+     * for is not run, records no step, and its result says why.
+     *
+     * @since 2.132.0
+     */
+    protected executeDecisionRequestsAsSteps(requests: AgentDecisionRequest[], finalPayload: unknown, agentTypePromptParams: Record<string, unknown> | undefined, params: ExecuteAgentParams): Promise<AgentDecisionResult[]>;
+    /** The most decision requests one turn may run: `decisionsMaxRequests`, or {@link MAX_DECISION_REQUESTS_PER_TURN}. */
+    private decisionRequestCap;
+    /**
+     * The most decision calls one turn's requests make in total, `forEachItemIn` items included:
+     * `decisionsMaxCallsPerTurn`, or {@link MAX_DECISION_CALLS_PER_TURN}.
+     */
+    private decisionCallBudget;
+    /** The most items one `forEachItemIn` request asks about: `decisionsMaxItems`, or its default. */
+    private decisionMaxItems;
+    /** A decision limit from the prompt params when it is a non-negative integer, or `fallback` when it is absent or anything else. */
+    private decisionLimit;
+    /**
+     * Hands out the turn's decision-call budget to its requests in order, before any of them runs.
+     * Each request gets the calls it wants while the budget lasts. The first one the budget cannot
+     * cover gets what is left, and the ones after it get none.
+     */
+    private allotDecisionCalls;
+    /**
+     * The decision calls a request makes with no budget: one, or one per `forEachItemIn` item up to
+     * `decisionsMaxItems`. A request that cannot make any, because it is not an object or its
+     * `forEachItemIn` is not an array, wants none. A request that fails before it asks, such as one
+     * with no valid question, still holds what its shape wants: the budget can then go unused, but
+     * it is never exceeded.
+     */
+    private decisionCallsWanted;
+    /**
+     * The result of a request the turn's decision-call budget left no calls for. It was not run.
+     * A budget of 0 turns decision calls off for the agent, so then asking again on a later turn
+     * cannot help, and the result does not invite it.
+     */
+    private overBudgetDecisionResult;
+    /** A request's id for its result, or its position when the model sent no usable id. */
+    private decisionRequestId;
+    /**
+     * Runs a `'Decision'` next step: an agent type's decision requests, answered with no LLM turn.
+     *
+     * Each request goes through the same path a loop turn's decisions take
+     * ({@link executeSingleDecisionRequestAsStep}), so it gets the same prompt default, state
+     * resolution and error handling, and is logged as a `Decision` run step. Where a loop turn's
+     * results go into the conversation, these come back to the agent type on the returned `'Retry'`
+     * (`decisionResults`), because it routes on them. So each answer keeps its whole distribution
+     * (`SummarizeDecisionAnswers`), which a path condition may read. A failed request is a result
+     * with `success: false`, never a failed run: what a failure means is the agent type's call.
+     *
+     * @since 6.2.0
+     */
+    protected executeDecisionStep<P>(params: ExecuteAgentParams, decision: BaseAgentNextStep<P>): Promise<BaseAgentNextStep<P>>;
+    /**
+     * Answers one decision request, either once against its `state` or once per item of its
+     * `forEachItemIn` array, and records it as a Decision step. The request is unchecked model
+     * output, so any error finishes the step as failed rather than escaping: this never throws
+     * once the step exists.
+     *
+     * @param callAllowance The most decision calls the request may make, from the turn's
+     * `decisionsMaxCallsPerTurn` budget. It caps a `forEachItemIn` request's items below
+     * `decisionsMaxItems`. A single-state request makes one call, and
+     * {@link executeDecisionRequestsAsSteps} never starts one the budget left without it.
+     * Unbounded by default.
+     * @param summarize how the typed answers are summarised for whoever reads them next; defaults
+     *                  to the loop turn's model-facing summary
+     * @since 2.132.0
+     */
+    protected executeSingleDecisionRequestAsStep(request: AgentDecisionRequest, finalPayload: unknown, agentTypePromptParams: Record<string, unknown> | undefined, params: ExecuteAgentParams, callAllowance?: number, summarize?: DecisionAnswerSummarizer): Promise<AgentDecisionResult>;
+    /** Asks the request's questions about one state, with the configured decision prompt. */
+    private decisionAsker;
+    /** Asks the questions once, against the request's state. */
+    private askOnce;
+    /**
+     * Asks the same questions of each item of a payload array, up to `decisionsMaxItems` and the
+     * request's share of the turn's call budget. Each item's call is its own child Decision step of
+     * the request's step, carrying that call's prompt run, as each iteration of a ForEach is a child
+     * step of its loop step.
+     */
+    private askForEachItem;
+    /** Asks about one item of a `forEachItemIn` request, recorded as a child step of the request's step. */
+    private askItemAsStep;
+    /**
+     * Links a decision call's prompt run to its step, as the Prompt step links its own, so the run's
+     * cost and token totals and its `MaxCostPerRun` / `MaxTokensPerRun` checks count the call.
+     */
+    protected attachDecisionPromptRun(step: MJAIAgentRunStepEntityExtended, result: AIDecisionRunResult): void;
+    /**
+     * Links the prompt run of a decision call the run stopped waiting for (a timeout or a cancellation)
+     * to its step, once the call settles. `AIDecisionRunner` writes the prompt run before it calls the
+     * model, so a stopped call still has one. The link keeps that row on the run's trace, and counts its
+     * usage in the run's cost and token totals when it settles before the run ends, as
+     * {@link attachDecisionPromptRun} does on time. The step may already be finalized, so the link is
+     * saved on its own. Never throws, and a call that never settles links nothing.
+     */
+    private linkLateDecisionPromptRun;
+    /**
+     * A literal state, or a value read from the payload: the whole payload for `payload`, one value
+     * for a `payload.` path.
+     */
+    private resolveDecisionState;
+    /** Reads a `payload.`-prefixed dotted path (or `payload` itself) from the payload. */
+    private resolvePayloadPath;
+    /** Strings pass through; anything else becomes indented JSON. */
+    private decisionStateText;
+    /** Finalizes the Decision step and builds the result the agent reads next turn. */
+    private finishDecisionStep;
+    /**
+     * Answers the decision requests a prompt returned, or holds them when the step that carries
+     * them can end the run, because then no turn would read their answers. Held requests run before
+     * the next prompt ({@link runHeldDecisions}), or are skipped if the run ends first
+     * ({@link skipHeldDecisions}). Skips them all, unasked, while the master switch is off
+     * ({@link DecisionsEnabled}) or the agent's `decisions` response field is.
+     */
+    private processTurnDecisions;
+    /**
+     * Why the decisions sent with this step would be paid for and never read, or `undefined` when
+     * the next turn reads them. Three ways a step's own outcome ends the run: a passing finishIf gate
+     * (only an Actions step or a single sub-agent is gated), a sub-agent's `terminateAfter`, and
+     * client tools sent with `taskComplete`, which end the run once the tools return. Every other
+     * step, including client tools without `taskComplete`, goes on to a prompt that reads them.
+     */
+    private decisionsHoldReason;
+    /**
+     * Runs the decision requests a prompt held back, now that the step that carried them has run
+     * without ending the run, so the prompt about to run reads their answers.
+     */
+    private runHeldDecisions;
+    /**
+     * Skips the decision requests a prompt held back, because the run ended before they could be
+     * asked: the step that carried them ended it, or it was cancelled, or an error was thrown out of
+     * the step loop. Called from the loop's terminate branch and from `Execute()`'s `finally`, so
+     * every way out logs them. The held state is cleared before the log line, so the second call on
+     * the terminate path logs nothing and each held request is logged exactly once.
+     *
+     * @param runEnd How the run ended, as a clause for the log line.
+     */
+    private skipHeldDecisions;
+    /** How the run ended, as a clause for held decision requests that a cancellation or an error left unasked. */
+    private runEndForHeldDecisions;
+    /**
+     * Injects decision results into the conversation as one tool-result message for the next turn.
+     *
+     * @since 2.132.0
+     */
+    protected injectDecisionResultsMessage(params: ExecuteAgentParams, results: AgentDecisionResult[]): void;
     /**
      * Creates a chat message containing sub-agent execution results.
      *
@@ -2332,6 +2667,52 @@ export declare class BaseAgent {
      * @private
      */
     private gatherPromptTemplateData;
+    /**
+     * Narrows the catalog once per run, on its first prompt (plan Task 3.7), and caches the result for
+     * every later step. With narrowing off, or the master switch ({@link DecisionsEnabled}) off, it
+     * asks nothing and records nothing, so the prompt describes the whole catalog. Never throws: any
+     * failure leaves the full catalog in place. It narrows the prose catalog only:
+     * {@link applyNativeTools} still declares every action and sub-agent.
+     */
+    private ensureCatalogNarrowing;
+    /**
+     * The run's limits, with actions left whole when the agent lacks Find Candidate Actions: a hidden
+     * action would then be unreachable. That case is logged as a warning when it keeps a long action
+     * list whole, since the agent asked for narrowing and did not get it.
+     */
+    private reachableCatalogNarrowingLimits;
+    /**
+     * Every item of the three lists as a narrowing candidate. An action or sub-agent with
+     * `MinExecutionsPerRun` set, and the Find Candidate tools, are pinned: always shown.
+     */
+    private catalogNarrowingCandidates;
+    /**
+     * Asks the one decision, records it as the `Catalog narrowing` step, and returns what to hide.
+     * Any failure is logged as a warning and hides nothing, so the prompt shows the full catalog.
+     */
+    private narrowCatalog;
+    /**
+     * The one decision call, against the opening request. Never throws, and never waits longer than
+     * {@link CATALOG_NARROWING_TIMEOUT_MS} or past the run's cancellation: a throw, a timeout and a
+     * cancelled run each come back as a failed result. Stopping also aborts the call, and links the
+     * prompt run it still returns to `step` once it does ({@link linkLateDecisionPromptRun}).
+     */
+    private askCatalogNarrowing;
+    /** Opens the `Catalog narrowing` Decision step with the decision's inputs. Without a run there is no step. */
+    private startCatalogNarrowingStep;
+    /** Finalizes the `Catalog narrowing` step: each narrowed list's counts, kept names and probabilities, or why it failed open. */
+    private finishCatalogNarrowingStep;
+    /** Logs that catalog narrowing failed open. */
+    private warnCatalogNarrowing;
+    /** The items of one list the prompt shows. Returns `items` itself when the run's narrowing hides none of them. */
+    private hideNarrowedOut;
+    /**
+     * One catalog section as the prompt shows it: `full` when the run's narrowing hides none of
+     * `items`, otherwise a {@link CatalogNarrowingNote} saying how many are hidden and how to reach
+     * them, then the items still shown. A hidden item can still be called. Fails OPEN, unlike the
+     * skill policy: an error shows `full` and logs a warning.
+     */
+    private narrowedCatalogSection;
     /**
      * Builds the agent-invariant {@link AgentBaseCatalog} — the resolved sub-agents + actions and
      * their formatted markdown, plus the base agent-type prompt params. Computed once per agent and
@@ -2372,6 +2753,40 @@ export declare class BaseAgent {
      * @since 2.131.0
      */
     protected buildAgentTypePromptParams(agentType: MJAIAgentTypeEntity | undefined, agent: MJAIAgentEntityExtended, runtimeOverrides?: Record<string, unknown>): Record<string, unknown>;
+    /**
+     * The agent and value pairs {@link warnOnceOnUnknownFinishIfMode} has already reported. It is
+     * process-wide because the prompt params are merged again for every run of an agent, and on every
+     * turn that carries runtime overrides. One warning per agent and value is enough. A run request
+     * can set the value, so what this keeps is bounded: see {@link FinishIfModeWarnings}.
+     */
+    private static readonly finishIfModeWarnings;
+    /**
+     * Warns, once per agent and value, when the merged `finishIfMode` is set but is not a
+     * {@link FinishIfMode}. {@link ResolveFinishIfMode} treats such a value as `'off'`, so without
+     * this a typo such as `"On"` or `"true"` would turn the agent's gates off without a word. An
+     * absent value is the default, so it is not reported.
+     */
+    private warnOnceOnUnknownFinishIfMode;
+    /**
+     * The master switch for decision-model use by this agent: `decisionsEnabled` in its merged
+     * agent-type prompt params (type default < agent < the run's `data.__agentTypePromptParams`).
+     * Anything but `true` is off, the default.
+     *
+     * While it is off the agent never asks a decision model on its own. Each automatic use checks it
+     * before it asks, whatever its own setting says: inline `decisions` ({@link processTurnDecisions}),
+     * `finishIf` gates ({@link finishIfSettings}), decision discovery ({@link isDecisionDiscoveryOnFor}),
+     * the payload change check ({@link isPayloadFeedbackCheckOn}), catalog narrowing
+     * ({@link ensureCatalogNarrowing}) and the Memory Manager's note gate. And
+     * {@link applyResponseTypeAutoAlignment} keeps the `decisions` and `finishIf` docs and response
+     * fields out of the prompt. While it is on, each use keeps its own setting, and each is off by default.
+     *
+     * Explicit uses never read it: a Flow agent's Decision step ({@link executeDecisionStep}) runs because
+     * someone placed it, and the task-graph Decision step and the Run Decision action call
+     * {@link AgentDecisionService} directly. That is why the check sits at each automatic use, not in the service.
+     *
+     * @param promptParams - The merged agent-type prompt params.
+     */
+    protected DecisionsEnabled(promptParams: Record<string, unknown> | undefined): boolean;
     /**
      * Applies auto-alignment rules to includeResponseTypeDefinition based on other flags.
      *
@@ -2385,6 +2800,10 @@ export declare class BaseAgent {
      * - includeCommandDocs → includeResponseTypeDefinition.commands
      * - includeForEachDocs → includeResponseTypeDefinition.forEach
      * - includeWhileDocs → includeResponseTypeDefinition.while
+     * - includeDecisionsDocs → includeResponseTypeDefinition.decisions
+     *
+     * While the master switch is off ({@link DecisionsEnabled}), the decisions and finishIf docs and
+     * response fields are off, even when set explicitly.
      *
      * @param params - The merged params object to modify in place
      * @param explicitResponseType - The explicitly set response type config from agent/runtime (not schema defaults)
@@ -2402,12 +2821,106 @@ export declare class BaseAgent {
      * @since 2.131.0
      */
     protected extractSchemaDefaults(schemaJson: string | null | undefined): Record<string, unknown>;
+    /**
+     * The finishIf settings of the current step, from its merged agent-type prompt params. A gate is
+     * evaluated when the master switch is on ({@link DecisionsEnabled}), `finishIfMode` is `shadow` or
+     * `on`, and `includeResponseTypeDefinition.finishIf` is not `false`; it ends the run only in `on`.
+     */
+    private finishIfSettings;
+    /** Whether a passing finishIf gate ends the run: only in `on` mode. */
+    private finishIfActs;
+    /**
+     * Whether an evaluated gate ends the run. In shadow mode a passing gate is only logged: the
+     * outcome is already recorded on its `Finish check` step, and the model takes its next turn.
+     */
+    private gateEndsRun;
+    /**
+     * Runs the finishIf gate after an Actions step, and returns the Success step when it passes.
+     * ForEach and While call executeActionsStep without a conversation message, and are never gated.
+     */
+    private finishAfterActions;
+    /**
+     * Runs the finishIf gate after a Sub-Agent step that succeeded without terminating, and returns
+     * the step with `terminate: true` when it passes, as `terminateAfter` would.
+     */
+    private finishAfterSubAgent;
+    /**
+     * Asks the finishIf questions about the step's results, then checks that the normal Success
+     * validation would allow the run to end. Records the check as a `Finish check` Decision step.
+     * Never throws: any error means the gate did not pass, and the run continues as it would have.
+     */
+    private evaluateFinishIf;
+    /**
+     * Asks each finishIf question as a Likelihood. Every one must reach the threshold. The call's
+     * prompt run is linked to the `Finish check` step, so the run's cost and tokens count it.
+     */
+    private askFinishIf;
+    /**
+     * Returns why the normal Success validation would refuse to end the run, or `undefined` when it
+     * allows it. The check must not count as a validation retry, so the counters are restored:
+     * otherwise a gate that keeps not passing could exhaust the retries and fail the run.
+     */
+    private finishIfValidationRefusal;
+    /** The Success step a passing gate returns after actions, in the shape of the client-tools `terminateAfterExecution` branch. */
+    private finishIfSuccessStep;
+    /** Finalizes the `Finish check` step with the outcome. A failure to save it never affects the run. */
+    private finalizeFinishCheckStep;
+    /**
+     * Whether the merged agent-type prompt params turn the payload change check on. It is off unless
+     * the master switch ({@link DecisionsEnabled}) and `payloadFeedbackCheck` are both `true`.
+     */
+    private isPayloadFeedbackCheckOn;
+    /**
+     * Runs the payload change check ({@link checkPayloadChanges}) on a step's applied payload changes
+     * when it applies: the analyzer flagged a change for feedback, the check is on
+     * ({@link isPayloadFeedbackCheckOn}), and a turn will read the result. A step that ends the run
+     * skips it: no call to pay for, and no message left in the conversation. Never throws.
+     */
+    private checkPayloadChangesWhenOn;
+    /**
+     * Whether the step ends the run, so no turn would read the payload change check's message: it
+     * terminates, or it is a `Success` or `Chat` step, which hand the run back to the caller.
+     */
+    private stepEndsRun;
+    /**
+     * The payload change check. Asks whether each change the analyzer flagged was intended, as one
+     * Likelihood per change in one decision call, and records it as a `Payload change check`
+     * Decision step. The changes judged unintended are listed in a message for the agent's next
+     * turn, which asks it to confirm or restore them.
+     *
+     * It never reverts or blocks a change: the agent decides. When the decision cannot answer,
+     * every change is accepted, as it is with the check off. Never throws.
+     */
+    private checkPayloadChanges;
+    /**
+     * What the payload change check's decision reads: the agent's own reasoning for the step (from its
+     * response, else from the step), its message, and the reasoning it gave with the change. The check
+     * never runs on a `Chat` or `Success` step, so the message comes from the response alone.
+     */
+    private payloadFeedbackContext;
+    /**
+     * Finalizes the `Payload change check` step with each change's probability and outcome. The step
+     * fails when no decision answered, and its error says why. A failure to save it never affects the run.
+     */
+    private finalizePayloadCheckStep;
+    /** Adds the payload change check's message to the conversation, for the agent's next turn. */
+    private injectPayloadCheckMessage;
+    /**
+     * The {@link AIPromptExecutionScope} of model work this run starts outside the agent's own turn —
+     * summarizing a range, compacting a message or the conversation, decision calls (FinishIf,
+     * discovery, catalog narrowing, decision requests, the payload change check) and self-check
+     * rubrics. Each built its params with only `contextUser`, so it ran on the platform's keys and
+     * default configuration inside a run on a customer's keys, and under a `'RuntimeOnly'` scope
+     * would have bypassed it.
+     */
+    private runPromptExecutionScope;
     /**
      * Whether THIS action may use the run's runtime API key for THIS driver class. The default is
      * yes: the run was started on those keys, and an action that calls a vendor on the user's behalf
      * (Generate Image) is doing what the prompts do. Override to narrow it — an agent that knows
      * which of its actions talk to which vendor can refuse everything else, and a refusal costs the
      * action nothing but the customer's key: it falls back to the platform key as if the run had none.
+     * Under a `'RuntimeOnly'` credential scope a refusal leaves the action with no key for that class.
      */
     protected actionMayUseRuntimeAPIKey(action: MJActionEntityExtended, driverClass: string, params: ExecuteAgentParams): boolean;
     /**
@@ -3023,8 +3536,10 @@ export declare class BaseAgent {
      * by one in-flight sub-agent would race the others' reads.
      *
      * Uses `structuredClone` (Node 17+) where available; falls back to a JSON
-     * round-trip for environments without it. Returns the original value on
-     * non-cloneable inputs.
+     * round-trip (`ToPlainJSON`) for environments without it AND when
+     * `structuredClone` throws (a Proxy such as a live JSONType `<Field>Object`
+     * view, or functions). Returns the original value — with an error logged —
+     * only when even the JSON clone fails.
      *
      * **JSON fallback caveats** — the round-trip is *not* shape-preserving:
      *   - `Date` → ISO string
@@ -3282,6 +3797,8 @@ export declare class BaseAgent {
      * them calls this after MJ's gates
      * (AcceptsSkills, Status, agent grant, user Run permission, the ActivationMode double gate) and
      * before anything activates. The default is the identity: MJ's gates are the whole policy.
+     * Catalog narrowing (plan Task 3.7) is not part of this policy: it runs after it, at the catalog
+     * site, and only hides skills from the prompt. An override never needs to call `super` for it.
      *
      * Override it to layer a policy MJ has no table for — a tenant licensing model, a per-organization
      * entitlement, a feature flag — and it applies everywhere at once. Without this seam a subclass