@elizaos/agent 2.0.0-alpha.192 → 2.0.0-alpha.196

package/packages/typescript/src/services/message.js

@@ -13,7 +13,7 @@ import { EventType } from "../types/events";
 import { ModelType } from "../types/model";
 import { incomingPipelineHookContext, modelStreamChunkPipelineHookContext, outgoingPipelineHookContext, parallelWithShouldRespondPipelineHookContext, preShouldRespondPipelineHookContext, } from "../types/pipeline-hooks";
 import { asUUID, ChannelType, ContentType } from "../types/primitives";
-import { composePromptFromState, getLocalServerUrl, parseBooleanFromText, parseKeyValueXml, truncateToCompleteSentence, } from "../utils";
+import { composePromptFromState, getLocalServerUrl, parseBooleanFromText, parseJSONObjectFromText, parseKeyValueXml, truncateToCompleteSentence, } from "../utils";
 import { AVAILABLE_CONTEXTS_STATE_KEY, attachAvailableContexts, CONTEXT_ROUTING_STATE_KEY, mergeContextRouting, parseContextRoutingMetadata, setContextRoutingMetadata, } from "../utils/context-routing";
 import { createStreamingContext, MarkableExtractor, ResponseStreamExtractor, } from "../utils/streaming";
 import { extractFirstSentence, hasFirstSentence, } from "../utils/text-splitting";
@@ -28,6 +28,7 @@ export const RESERVED_XML_KEYS = new Set([
     "simple",
     "providers",
 ]);
+const PLANNER_CONTROL_ACTIONS = new Set(["REPLY", "RESPOND", "IGNORE", "STOP"].map(normalizeActionIdentifier));
 function escapeRegex(value) {
     return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
@@ -197,12 +198,157 @@ function normalizePlannerActions(parsedXml, runtime) {
     const finalActions = !runtime.isActionPlanningEnabled() && normalizedActions.length > 1
         ? [normalizedActions[0]]
         : normalizedActions;
-    if (finalActions.length > 0) {
-        return finalActions;
+    const actionLookup = buildRuntimeActionLookup(runtime);
+    const validActions = finalActions.filter((actionName) => {
+        const normalized = normalizeActionIdentifier(actionName);
+        if (!normalized) {
+            return false;
+        }
+        if (PLANNER_CONTROL_ACTIONS.has(normalized)) {
+            return true;
+        }
+        const resolvedAction = resolveRuntimeAction(actionLookup, actionName);
+        if (resolvedAction) {
+            return true;
+        }
+        runtime.logger.warn({
+            src: "service:message",
+            actionName,
+        }, "Dropping unknown planner action");
+        return false;
+    });
+    if (validActions.length > 0) {
+        return validActions;
     }
     const replyText = typeof parsedXml.text === "string" ? parsedXml.text.trim() : "";
     return replyText.length > 0 ? ["REPLY"] : ["IGNORE"];
 }
+function normalizePlannerProviders(parsedXml, runtime) {
+    const rawProviders = parsedXml.providers;
+    const providerNames = (() => {
+        if (typeof rawProviders === "string") {
+            const trimmedProviders = rawProviders.trim();
+            if ((trimmedProviders.startsWith("[") && trimmedProviders.endsWith("]")) ||
+                (trimmedProviders.startsWith("{") && trimmedProviders.endsWith("}"))) {
+                try {
+                    const parsedJson = JSON.parse(trimmedProviders);
+                    if (Array.isArray(parsedJson)) {
+                        return parsedJson
+                            .map((providerName) => String(providerName).trim())
+                            .filter((providerName) => providerName.length > 0);
+                    }
+                    if (typeof parsedJson === "object" &&
+                        parsedJson !== null &&
+                        Array.isArray(parsedJson.providers)) {
+                        return (parsedJson.providers
+                            .map((providerName) => String(providerName).trim())
+                            .filter((providerName) => providerName.length > 0));
+                    }
+                }
+                catch {
+                    // Fall through to XML/comma parsing below.
+                }
+            }
+            if (rawProviders.includes("<provider>") ||
+                rawProviders.includes("<provider ")) {
+                const providers = Array.from(rawProviders.matchAll(/<provider>([\s\S]*?)<\/provider>/g))
+                    .map((match) => match[1]?.trim() ?? "")
+                    .filter((providerName) => providerName.length > 0);
+                if (providers.length > 0) {
+                    return providers;
+                }
+            }
+            return rawProviders
+                .split(/[\n,;]/)
+                .map((providerName) => providerName.replace(/^[\s"'[\](){}]+|[\s"'[\](){}]+$/g, ""))
+                .map((providerName) => providerName.trim())
+                .filter((providerName) => providerName.length > 0);
+        }
+        if (Array.isArray(rawProviders)) {
+            return rawProviders
+                .map((providerName) => String(providerName).trim())
+                .filter((providerName) => providerName.length > 0);
+        }
+        return [];
+    })();
+    if (!runtime) {
+        return providerNames;
+    }
+    const providerLookup = new Map();
+    for (const provider of runtime.providers ?? []) {
+        const normalized = normalizeActionIdentifier(provider.name);
+        if (!normalized || providerLookup.has(normalized)) {
+            continue;
+        }
+        providerLookup.set(normalized, provider.name);
+    }
+    const normalizedProviders = providerNames
+        .map((providerName) => {
+        const canonicalProvider = providerLookup.get(normalizeActionIdentifier(providerName));
+        if (canonicalProvider) {
+            return canonicalProvider;
+        }
+        runtime.logger.warn({
+            src: "service:message",
+            providerName,
+        }, "Dropping unknown planner provider");
+        return "";
+    })
+        .filter((providerName) => providerName.length > 0);
+    if (normalizedProviders.length === 0) {
+        return normalizedProviders;
+    }
+    const providerDefinitions = new Map((runtime.providers ?? []).map((provider) => [
+        normalizeActionIdentifier(provider.name),
+        provider,
+    ]));
+    const expandedProviders = [...normalizedProviders];
+    const seenProviders = new Set(expandedProviders.map((providerName) => normalizeActionIdentifier(providerName)));
+    for (let index = 0; index < expandedProviders.length; index += 1) {
+        const providerName = expandedProviders[index];
+        const providerDefinition = providerDefinitions.get(normalizeActionIdentifier(providerName));
+        const companionProviders = providerDefinition?.companionProviders ?? [];
+        for (const companionProvider of companionProviders) {
+            const canonicalCompanion = providerLookup.get(normalizeActionIdentifier(companionProvider));
+            if (!canonicalCompanion) {
+                runtime.logger.warn({
+                    src: "service:message",
+                    providerName,
+                    companionProvider,
+                }, "Dropping unknown companion provider");
+                continue;
+            }
+            const normalizedCompanion = normalizeActionIdentifier(canonicalCompanion);
+            if (seenProviders.has(normalizedCompanion)) {
+                continue;
+            }
+            seenProviders.add(normalizedCompanion);
+            expandedProviders.push(canonicalCompanion);
+        }
+    }
+    return expandedProviders;
+}
+const CORE_RESPONSE_STATE_PROVIDERS = [
+    "ENTITIES",
+    "CHARACTER",
+    "RECENT_MESSAGES",
+    "ACTIONS",
+    "PROVIDERS",
+];
+const STRUCTURED_RESPONSE_STATE_PROVIDERS = ["ACTIONS", "PROVIDERS"];
+const FOCUSED_PROVIDER_REPLY_STATE_PROVIDERS = ["CHARACTER", "RECENT_MESSAGES"];
+function composeResponseState(runtime, message, skipCache = false) {
+    return runtime.composeState(message, CORE_RESPONSE_STATE_PROVIDERS, true, skipCache);
+}
+function composeStructuredResponseState(runtime, message, skipCache = false) {
+    return runtime.composeState(message, STRUCTURED_RESPONSE_STATE_PROVIDERS, false, skipCache);
+}
+function composeProviderGroundedResponseState(runtime, message, providers, skipCache = false) {
+    return runtime.composeState(message, [...CORE_RESPONSE_STATE_PROVIDERS, ...providers], false, skipCache);
+}
+function composeFocusedProviderReplyState(runtime, message, providers, skipCache = false) {
+    return runtime.composeState(message, [...FOCUSED_PROVIDER_REPLY_STATE_PROVIDERS, ...providers], true, skipCache);
+}
 /**
  * Escape Handlebars syntax in a string to prevent template injection.
  *
@@ -334,6 +480,193 @@ function isStopResponse(responseContent) {
 function normalizeActionIdentifier(actionName) {
     return actionName.trim().toUpperCase().replace(/_/g, "");
 }
+const PROVIDER_FOLLOWUP_PASSIVE_ACTIONS = new Set(["REPLY", "RESPOND", "NONE"].map(normalizeActionIdentifier));
+function shouldRunProviderFollowup(responseContent) {
+    if (!responseContent?.providers?.length) {
+        return false;
+    }
+    const normalizedActions = (responseContent.actions ?? [])
+        .map((actionName) => typeof actionName === "string"
+        ? normalizeActionIdentifier(actionName)
+        : "")
+        .filter((actionName) => actionName.length > 0);
+    if (normalizedActions.length === 0) {
+        return true;
+    }
+    return normalizedActions.every((actionName) => PROVIDER_FOLLOWUP_PASSIVE_ACTIONS.has(actionName));
+}
+function buildProviderFollowupPrompt(basePrompt) {
+    return `${basePrompt}
+
+[PROVIDER FOLLOW-UP]
+The requested providers have already been executed, and their grounded results are now present in context above.
+Use those provider results to produce the final reply and/or action plan for this turn.
+Do not ask for the same providers again.
+If the provider results fully answer the user, reply directly.
+If KNOWLEDGE contains a direct answer, prefer that grounded answer even when AVAILABLE_DOCUMENTS lists multiple files.
+Do not ask "which file?" when the grounded KNOWLEDGE result already resolves the request.`;
+}
+function shouldAttemptProviderRescue(responseContent) {
+    if (!responseContent) {
+        return false;
+    }
+    if ((responseContent.providers?.length ?? 0) > 0) {
+        return false;
+    }
+    const normalizedActions = (responseContent.actions ?? [])
+        .map((actionName) => typeof actionName === "string"
+        ? normalizeActionIdentifier(actionName)
+        : "")
+        .filter((actionName) => actionName.length > 0);
+    if (normalizedActions.length === 0) {
+        return true;
+    }
+    return normalizedActions.every((actionName) => PROVIDER_FOLLOWUP_PASSIVE_ACTIONS.has(actionName));
+}
+function buildProviderSelectionPrompt(draftReply) {
+    const trimmedDraftReply = draftReply?.trim() ?? "";
+    const draftReplySection = trimmedDraftReply.length > 0
+        ? `draft_reply:\n${trimmedDraftReply.replace(/<\/response>/gi, "<\\/response>")}\n\n`
+        : "";
+    const draftReplyRules = trimmedDraftReply.length > 0
+        ? [
+            "- if the draft reply asks the user to resend, restate, or clarify information that may already exist in provider context, choose the relevant providers instead of sending the draft reply as-is",
+            '- when the recent conversation already identifies a prior upload or knowledge-base question, prefer grounded provider lookup over asking "which file?" again',
+        ]
+        : [];
+    return `task: Decide whether any providers should be called before sending the assistant's reply.
+
+available provider catalog:
+{{providers}}
+
+recent conversation:
+{{recentMessages}}
+
+${draftReplySection}rules[${4 + draftReplyRules.length}]:
+- choose providers only when they can supply grounded information needed before the assistant replies
+- uploaded files, documents, prior uploads, and knowledge-base questions should use the relevant providers before asking the user to resend the material
+- if the user asks about an uploaded file or document and AVAILABLE_DOCUMENTS is available, prefer AVAILABLE_DOCUMENTS together with KNOWLEDGE before sending any clarification reply
+- return an empty providers field when no provider lookup is needed
+- do not include actions, text, or thought in the output
+${draftReplyRules.join("\n")}
+
+output:
+Return JSON or XML containing only provider names. No prose before or after it. No <think>.
+
+Examples:
+- user asks: "what is the qa codeword from the uploaded file?"
+  draft reply: "Which file are you referring to?"
+  output: {"providers":["AVAILABLE_DOCUMENTS","KNOWLEDGE"]}
+- user asks: "what is the qa codeword from the uploaded file?"
+  draft reply: "I don't have the file in my context. Which file contains the QA codeword?"
+  output: {"providers":["AVAILABLE_DOCUMENTS","KNOWLEDGE"]}
+- user asks: "thanks, that's all"
+  draft reply: "Glad to help."
+  output: {"providers":[]}`;
+}
+async function recoverProvidersForTurn(args) {
+    const prompt = composePromptFromState({
+        state: args.state,
+        template: buildProviderSelectionPrompt(args.draftReply),
+    });
+    try {
+        const result = await args.runtime.useModel(ModelType.TEXT_LARGE, {
+            prompt,
+            ...(args.attachments ? { attachments: args.attachments } : {}),
+        });
+        const rawResponse = typeof result === "string" ? result : "";
+        const parsed = parseKeyValueXml(rawResponse) ??
+            parseJSONObjectFromText(rawResponse);
+        const normalizedProviders = normalizePlannerProviders(parsed ?? { providers: rawResponse }, args.runtime);
+        if (normalizedProviders.length > 0) {
+            return normalizedProviders;
+        }
+        const shouldUseKnowledge = await shouldUseKnowledgeProviders(args.runtime, args.state, args.attachments);
+        return shouldUseKnowledge ? ["AVAILABLE_DOCUMENTS", "KNOWLEDGE"] : [];
+    }
+    catch (error) {
+        args.runtime.logger.warn({
+            src: "service:message",
+            error: error instanceof Error ? error.message : String(error),
+        }, "Provider rescue model call failed");
+        return [];
+    }
+}
+function buildGroundedFallbackReplyPrompt() {
+    return `task: Write the next assistant reply using grounded context.
+
+grounded context:
+{{providers}}
+
+recent conversation:
+{{recentMessages}}
+
+rules[5]:
+- answer directly from grounded context when it fully answers the user
+- do not ask the user to resend, rename, or specify a file if grounded document or knowledge context already answers the request
+- do not say you cannot access the file when grounded context is already present above
+- if KNOWLEDGE contains a direct answer, prefer that grounded answer even when AVAILABLE_DOCUMENTS lists multiple files
+- if grounded context is still insufficient, say exactly what is missing
+- return only the reply text
+
+output:
+Plain text only. No XML, JSON, TOON, bullets, or <think>.`;
+}
+function buildKnowledgeProviderDecisionPrompt() {
+    return `task: Decide whether the assistant should consult uploaded-document or knowledge providers before replying.
+
+available provider catalog:
+{{providers}}
+
+recent conversation:
+{{recentMessages}}
+
+rules[5]:
+- return true when the user is asking about an uploaded file, document, prior upload, or knowledge-base content
+- return true when the answer is likely already stored in uploaded documents or semantic knowledge search
+- when AVAILABLE_DOCUMENTS or KNOWLEDGE is available and the user refers to an uploaded file or prior upload, return true
+- return false for generic chat, thanks, or requests that clearly do not depend on uploaded or knowledge-base content
+- return only the structured output, with no prose
+
+output:
+Return JSON or XML only.
+
+Examples:
+- user asks: "what is the qa codeword from the uploaded file?" -> {"useKnowledgeProviders":true}
+- user asks: "thanks, that's all" -> {"useKnowledgeProviders":false}`;
+}
+async function shouldUseKnowledgeProviders(runtime, state, attachments) {
+    const prompt = composePromptFromState({
+        state,
+        template: buildKnowledgeProviderDecisionPrompt(),
+    });
+    try {
+        const result = await runtime.useModel(ModelType.TEXT_LARGE, {
+            prompt,
+            ...(attachments ? { attachments } : {}),
+        });
+        const rawResponse = typeof result === "string" ? result : "";
+        const parsed = parseKeyValueXml(rawResponse) ??
+            parseJSONObjectFromText(rawResponse);
+        const value = parsed?.useKnowledgeProviders ??
+            parsed?.use_knowledge_providers ??
+            rawResponse;
+        if (typeof value === "boolean") {
+            return value;
+        }
+        if (typeof value === "string") {
+            return value.trim().toLowerCase() === "true";
+        }
+        return false;
+    }
+    catch (error) {
+        runtime.logger.warn({
+            src: "service:message",
+            error: error instanceof Error ? error.message : String(error),
+        }, "Knowledge provider decision model call failed");
+        return false;
+    }
+}
 function buildRuntimeActionLookup(runtime) {
     const actionMap = new Map();
     for (const action of runtime.actions ?? []) {
@@ -728,6 +1061,16 @@ function prepareShouldRespondState(state) {
         text: providersText,
     };
 }
+function isBenchmarkMode(state) {
+    const benchmarkFlag = state.values?.benchmark_has_context;
+    if (typeof benchmarkFlag === "boolean") {
+        return benchmarkFlag;
+    }
+    if (typeof benchmarkFlag === "string") {
+        return parseBooleanFromText(benchmarkFlag);
+    }
+    return false;
+}
 /**
  * Default implementation of the MessageService interface.
  * This service handles the complete message processing pipeline including:
@@ -1322,7 +1665,7 @@ export class DefaultMessageService {
         }
         const promptAttachments = resolvePromptAttachments(message.content.attachments);
         // Compose initial state (after incoming hooks so providers/actions text matches this turn)
-        let state = await runtime.composeState(message, ["ENTITIES", "CHARACTER", "RECENT_MESSAGES", "ACTIONS"], true, false);
+        let state = await composeResponseState(runtime, message);
         state = attachAvailableContexts(state, runtime);
         const metadata = typeof message.content.metadata === "object" &&
             message.content.metadata !== null
@@ -1392,7 +1735,7 @@ export class DefaultMessageService {
                 runtime.stateCache.delete(message.id);
                 runtime.stateCache.delete(`${message.id}_action_results`);
             }
-            state = await runtime.composeState(message, ["ENTITIES", "CHARACTER", "RECENT_MESSAGES", "ACTIONS"], true, false);
+            state = await composeResponseState(runtime, message);
             state = attachAvailableContexts(state, runtime);
         }
         let responseContent = null;
@@ -1445,8 +1788,44 @@ export class DefaultMessageService {
             if (responseContent && message.id) {
                 responseContent.inReplyTo = createUniqueUuid(runtime, message.id);
             }
+            const providerStateValues = {
+                [AVAILABLE_CONTEXTS_STATE_KEY]: state.values?.[AVAILABLE_CONTEXTS_STATE_KEY],
+                [CONTEXT_ROUTING_STATE_KEY]: state.values?.[CONTEXT_ROUTING_STATE_KEY],
+            };
             if (responseContent?.providers && responseContent.providers.length > 0) {
-                state = await runtime.composeState(message, responseContent.providers, false, false);
+                state = withContextRoutingValues(await composeProviderGroundedResponseState(runtime, message, responseContent.providers), providerStateValues);
+            }
+            if (responseContent && shouldRunProviderFollowup(responseContent)) {
+                const providerFollowupState = responseContent.providers && responseContent.providers.length > 0
+                    ? withContextRoutingValues(await composeFocusedProviderReplyState(runtime, message, responseContent.providers), providerStateValues)
+                    : state;
+                runtime.logger.info({
+                    src: "service:message",
+                    providers: responseContent.providers ?? [],
+                    actions: responseContent.actions ?? [],
+                }, "Running provider follow-up pass");
+                const providerContinuation = await this.runSingleShotCore(runtime, message, providerFollowupState, opts, responseId, promptAttachments, {
+                    precomposedState: providerFollowupState,
+                    failureStage: "answering from requested provider results",
+                    providerFollowup: true,
+                });
+                responseContent = providerContinuation.responseContent;
+                responseMessages = providerContinuation.responseMessages;
+                state = providerContinuation.state;
+                mode = providerContinuation.mode;
+                if (responseContent && message.id) {
+                    responseContent.inReplyTo = createUniqueUuid(runtime, message.id);
+                }
+                runtime.logger.info({
+                    src: "service:message",
+                    finalActions: responseContent?.actions ?? [],
+                    finalProviders: responseContent?.providers ?? [],
+                    hasText: typeof responseContent?.text === "string" &&
+                        responseContent.text.length > 0,
+                }, "Provider follow-up pass completed");
+                if (responseContent?.providers && responseContent.providers.length > 0) {
+                    state = withContextRoutingValues(await runtime.composeState(message, responseContent.providers, false, false), providerStateValues);
+                }
             }
             // Save response memory to database.
             // - simple mode: persists after hooks in the branch below.
@@ -1623,7 +2002,9 @@ export class DefaultMessageService {
             return [];
         }, responseMessages);
         await runEvaluate();
-        if (opts.continueAfterActions && message.id) {
+        if (opts.continueAfterActions &&
+            message.id &&
+            !isBenchmarkMode(state)) {
             const taskCompletion = await runtime.getCache(getTaskCompletionCacheKey(message.id));
             await runtime.deleteCache(getTaskCompletionCacheKey(message.id));
             if (taskCompletion?.assessed &&
@@ -1935,7 +2316,6 @@ export class DefaultMessageService {
                 shouldRespond: false,
                 skipEvaluation: true,
                 reason: "no room context",
-                primaryContext: "general",
             };
         }
         function normalizeEnvList(value) {
@@ -1976,7 +2356,6 @@ export class DefaultMessageService {
                 shouldRespond: true,
                 skipEvaluation: true,
                 reason: `private channel: ${roomType}`,
-                primaryContext: "general",
             };
         }
         // 2. Specific sources (e.g., client_chat): always respond
@@ -1985,7 +2364,6 @@ export class DefaultMessageService {
                 shouldRespond: true,
                 skipEvaluation: true,
                 reason: `whitelisted source: ${sourceStr}`,
-                primaryContext: "general",
             };
         }
         // 3. Platform mentions and replies: always respond
@@ -1996,7 +2374,6 @@ export class DefaultMessageService {
                 shouldRespond: true,
                 skipEvaluation: true,
                 reason: `platform ${mentionType}`,
-                primaryContext: "general",
             };
         }
         // 4. Mixed-address messages should still reach the agent when the text
@@ -2006,7 +2383,6 @@ export class DefaultMessageService {
                 shouldRespond: true,
                 skipEvaluation: true,
                 reason: "text address with tagged participants",
-                primaryContext: "general",
             };
         }
         // 5. Clear self-modification requests should bypass the ignore-biased
@@ -2262,7 +2638,7 @@ export class DefaultMessageService {
                 responseContent.inReplyTo = createUniqueUuid(runtime, message.id);
             }
             if (responseContent.providers && responseContent.providers.length > 0) {
-                accumulatedState = withActionResults(withContextRoutingValues(await runtime.composeState(message, responseContent.providers, false, false), contextRoutingStateValues), traceActionResults);
+                accumulatedState = withActionResults(withContextRoutingValues(await composeProviderGroundedResponseState(runtime, message, responseContent.providers), contextRoutingStateValues), traceActionResults);
             }
             else {
                 accumulatedState = withActionResults(continuation.state, traceActionResults);
@@ -2359,7 +2735,7 @@ export class DefaultMessageService {
             responseContent.inReplyTo = createUniqueUuid(runtime, message.id);
         }
         if (responseContent.providers && responseContent.providers.length > 0) {
-            accumulatedState = withTaskCompletion(withActionResults(withContextRoutingValues(await runtime.composeState(message, responseContent.providers, false, false), contextRoutingStateValues), initialActionResults), taskCompletion);
+            accumulatedState = withTaskCompletion(withActionResults(withContextRoutingValues(await composeProviderGroundedResponseState(runtime, message, responseContent.providers), contextRoutingStateValues), initialActionResults), taskCompletion);
         }
         else {
             accumulatedState = withTaskCompletion(withActionResults(continuation.state, initialActionResults), taskCompletion);
@@ -2439,7 +2815,7 @@ export class DefaultMessageService {
     async runSingleShotCore(runtime, message, state, opts, responseId, promptAttachments, overrides) {
         state =
             overrides?.precomposedState ??
-                (await runtime.composeState(message, ["ACTIONS"], false, false));
+                (await composeStructuredResponseState(runtime, message));
         if (!state.values?.actionNames) {
             runtime.logger.warn({ src: "service:message" }, "actionNames data missing from state");
         }
@@ -2456,8 +2832,11 @@ export class DefaultMessageService {
         const optimizedResponseService = runtime.getService(OPTIMIZED_PROMPT_SERVICE);
         const baselineResponseTemplate = runtime.character.templates?.messageHandlerTemplate ||
             messageHandlerTemplate;
-        const prompt = overrides?.prompt ||
+        let prompt = overrides?.prompt ||
             resolveOptimizedPrompt(optimizedResponseService, "response", baselineResponseTemplate);
+        if (overrides?.providerFollowup) {
+            prompt = buildProviderFollowupPrompt(prompt);
+        }
         // Use dynamicPromptExecFromState for structured output with validation
         setTrajectoryPurpose("response");
         const parsedXml = await runtime.dynamicPromptExecFromState({
@@ -2484,6 +2863,13 @@ export class DefaultMessageService {
                     validateField: false,
                     streamField: false,
                 },
+                {
+                    field: "providers",
+                    description: "Optional provider names to call before the final reply or action. Use an empty field when no provider lookup is needed.",
+                    required: false,
+                    validateField: false,
+                    streamField: false,
+                },
                 // WHY streamField: true? This is the user-facing output - stream it!
                 // WHY validateField default? At level 1, we want to validate text integrity
                 {
@@ -2515,7 +2901,7 @@ export class DefaultMessageService {
                 ...parsedXml,
                 thought: String(parsedXml.thought || ""),
                 actions: finalActions,
-                providers: [],
+                providers: normalizePlannerProviders(parsedXml, runtime),
                 text: String(parsedXml.text || ""),
                 simple: parsedXml.simple === true || parsedXml.simple === "true",
             };
@@ -2590,6 +2976,10 @@ Output ONLY the continuation, starting immediately after the last character abov
             }
             else {
                 runtime.logger.warn({ src: "service:message" }, "dynamicPromptExecFromState returned null");
+                const groundedFallback = await this.tryGroundedFallbackReply(runtime, message, state, responseId, promptAttachments);
+                if (groundedFallback) {
+                    return groundedFallback;
+                }
                 return await this.buildStructuredFailureReply(runtime, message, state, responseId, overrides?.failureStage ?? "preparing the reply");
             }
         }
@@ -2601,6 +2991,23 @@ Output ONLY the continuation, starting immediately after the last character abov
                 mode: "none",
             };
         }
+        if (!overrides?.providerFollowup &&
+            shouldAttemptProviderRescue(responseContent)) {
+            const rescuedProviders = await recoverProvidersForTurn({
+                runtime,
+                state,
+                draftReply: String(responseContent.text || ""),
+                attachments: promptAttachments,
+            });
+            if (rescuedProviders.length > 0) {
+                runtime.logger.info({
+                    src: "service:message",
+                    rescuedProviders,
+                    originalActions: responseContent.actions ?? [],
+                }, "Selected providers during reply rescue pass");
+                responseContent.providers = rescuedProviders;
+            }
+        }
         // Action parameter repair (Python parity):
         // If the model selected actions with required parameters but omitted <params>,
         // do a second pass asking for ONLY a <params> block.
@@ -2669,8 +3076,8 @@ Output ONLY the continuation, starting immediately after the last character abov
                 responseContent.params = repairParsed.params;
             }
         }
+        const benchmarkMode = isBenchmarkMode(state);
         // Benchmark mode (Python parity): force action-based loop when benchmark context is present.
-        const benchmarkMode = state.values.benchmark_has_context === true;
         if (benchmarkMode) {
             if (!responseContent.actions || responseContent.actions.length === 0) {
                 responseContent.actions = ["REPLY"];
@@ -2731,6 +3138,64 @@ Output ONLY the continuation, starting immediately after the last character abov
                     : "actions",
         };
     }
+    async tryGroundedFallbackReply(runtime, message, state, responseId, promptAttachments) {
+        let groundedState = state;
+        const selectedProviders = await recoverProvidersForTurn({
+            runtime,
+            state,
+            attachments: promptAttachments,
+        });
+        if (selectedProviders.length > 0) {
+            groundedState = await composeFocusedProviderReplyState(runtime, message, selectedProviders);
+        }
+        const prompt = composePromptFromState({
+            state: groundedState,
+            template: buildGroundedFallbackReplyPrompt(),
+        });
+        try {
+            const result = await runtime.useModel(ModelType.TEXT_SMALL, {
+                prompt,
+                ...(promptAttachments ? { attachments: promptAttachments } : {}),
+            });
+            const text = typeof result === "string" ? result.trim() : "";
+            if (!text) {
+                return null;
+            }
+            const responseContent = {
+                thought: selectedProviders.length > 0
+                    ? "Grounded fallback reply from selected providers"
+                    : "Grounded fallback reply",
+                actions: ["REPLY"],
+                providers: selectedProviders,
+                text,
+                simple: true,
+                responseId,
+            };
+            const responseMessages = [
+                {
+                    id: responseId,
+                    entityId: runtime.agentId,
+                    agentId: runtime.agentId,
+                    content: responseContent,
+                    roomId: message.roomId,
+                    createdAt: Date.now(),
+                },
+            ];
+            return {
+                responseContent,
+                responseMessages,
+                state: groundedState,
+                mode: "simple",
+            };
+        }
+        catch (error) {
+            runtime.logger.warn({
+                src: "service:message",
+                error: error instanceof Error ? error.message : String(error),
+            }, "Grounded fallback reply generation failed");
+            return null;
+        }
+    }
     async buildStructuredFailureReply(runtime, message, state, responseId, stage) {
         const failure = getStructuredOutputFailure(state);
         const recentMessages = typeof state.values?.recentMessages === "string" &&

package/packages/typescript/src/types/components.d.ts

@@ -246,6 +246,12 @@ export interface Provider {
      * include in the planner's state composition for a given turn.
      */
     contexts?: AgentContext[];
+    /**
+     * Additional providers that should run alongside this provider when it is
+     * selected by the planner. Use this for provider composition, not semantic
+     * routing.
+     */
+    companionProviders?: string[];
     /** Data retrieval function */
     get: (runtime: IAgentRuntime, message: Memory, state: State) => Promise<ProviderResult>;
 }