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

package/dist/decision-discovery.js

@@ -0,0 +1,511 @@
+/**
+ * @fileoverview Decision discovery (typed-decision plan, Task 3.1): the pure half.
+ *
+ * When the user names no agent, a conversation manager such as Sage takes two turns to delegate: it
+ * calls Find Candidate Agents, then reads the rows and picks one. With the Loop prompt param
+ * `decisionDiscovery` on, `BaseAgent` instead asks one decision before the first prompt of a
+ * conversation's opening turn: a Choice over the agents the user may run, and a Likelihood that a
+ * specialist agent should handle the request. When both answers are confident, a `<suggested_agent>`
+ * system message reaches the first prompt, so the agent can delegate in its first turn. These helpers
+ * build the options and questions, judge the answers and format the message. The call, the
+ * `Agent discovery` step and the injection live on `BaseAgent`.
+ *
+ * It fails safe: after an error, a timeout, an unusable answer or an unsure one, nothing is injected
+ * and the agent behaves as it did before. A follow-up turn is never asked about (see
+ * {@link IsOpeningTurn}), so discovery never pulls the agent away from one it has already engaged.
+ *
+ * Known limitation, kept on purpose: the Likelihood does not name the options, so "none of these
+ * agents fits" cannot be expressed (see {@link DECISION_DISCOVERY_APPLIES_INSTRUCTIONS}).
+ *
+ * @module @memberjunction/ai-agents
+ */
+import { ApplyPlattCalibration } from '@memberjunction/ai';
+import { ConversationUtility, DescribeAnsweringModel, FindDecisionCalibration } from '@memberjunction/ai-core-plus';
+import { AIAgentPermissionHelper } from '@memberjunction/ai-engine-base';
+import { IsPlainObject, NormalizeUUID, UUIDsEqual } from '@memberjunction/global';
+/**
+ * The most options the Choice ever offers. It always applies: the limit is this, or the decision
+ * model's declared `MaxChoiceOptions` when that is smaller. A larger catalog is first narrowed to
+ * the limit by the semantic search Find Candidate Agents uses.
+ */
+export const DECISION_DISCOVERY_MAX_OPTIONS = 25;
+/**
+ * The least **calibrated** confidence at which the suggestion is shown (see
+ * {@link DECISION_DISCOVERY_CALIBRATION}). Both the Choice's confidence and the Likelihood that any
+ * agent applies must reach it.
+ *
+ * Set from the agent-discovery Decision Eval (plan Task 3.1, 2026-09-29): 258 labelled requests, 198
+ * for one of 33 agents and 60 for none, three repeats per model, calibrated out of fold, and scored
+ * as production would, so an answer after {@link DECISION_DISCOVERY_TIMEOUT_MS} injects nothing. At a
+ * calibrated 0.85, Jev's suggestion covered 21.7% of the requests meant for an agent, and named the
+ * right agent for 95.3% of those it covered. It was shown for 5.0% of the requests meant for no agent,
+ * all of them multi-agent workflows. Every Jev discovery but the run's first, which loaded the
+ * embedding model, finished within the timeout. LLM Decision finished within it for at least 67.7% of
+ * requests, and covered at least 16.0% at 92.6% precision, shown for 5.0%. A wrong suggestion costs
+ * more than a missed one, which is only the two-turn flow the agent used before, so the threshold
+ * favours precision. On raw probabilities the old 0.7 almost never fired: Jev's raw any-applies
+ * Likelihood never passed 0.8, so it covered 6.9%.
+ */
+export const DECISION_DISCOVERY_MIN_CONFIDENCE = 0.85;
+/**
+ * Platt calibration of the discovery answers, each tied to the exact model it was fitted on (see
+ * `FindDecisionCalibration` in `@memberjunction/ai-core-plus`): the MJ decision model that answered
+ * (`ModelName`, from `modelInfo.modelName`) and the model its driver reports behind it
+ * (`ResolvedModel`, from `DecisionResult.ResolvedModel`). A model's raw answers are not calibrated:
+ * Jev's raw any-applies Likelihood sits between 0.1 and 0.8 whatever the request. Any other model,
+ * including Jev at another version or `LLM Decision` answered by another chat model, is treated as
+ * unsure, so its answer suggests nothing.
+ *
+ * Fitted on the agent-discovery Decision Eval (2026-09-29; 258 requests, 3 repeats per model, 774
+ * answers each): the Choice's confidence against whether it named the labelled agent (594 answers
+ * to requests meant for an agent), and the Likelihood against whether the request was meant for an
+ * agent (all 774). Every fit converged (5 to 7 Newton iterations; a 60-digit refit agrees to 4
+ * places).
+ * - **Jev** at its pinned `APIName`, `typesafe/jev-1.13-20260917`, which it reports back as the
+ *   resolved model.
+ * - **LLM Decision** when its chat model is GPT-OSS-120B, which answered all 774 of its runs.
+ *
+ * Refit, and add the new pair, whenever a model, its version, the questions or the catalog's shape
+ * changes.
+ */
+export const DECISION_DISCOVERY_CALIBRATION = Object.freeze([
+    Object.freeze({
+        ModelName: 'Jev',
+        ResolvedModel: 'typesafe/jev-1.13-20260917',
+        Calibration: Object.freeze({ Confidence: Object.freeze({ A: 0.4412, B: 0.4571 }), AnyApplies: Object.freeze({ A: 1.2469, B: 1.7700 }) })
+    }),
+    Object.freeze({
+        ModelName: 'LLM Decision',
+        ResolvedModel: 'GPT-OSS-120B',
+        Calibration: Object.freeze({ Confidence: Object.freeze({ A: 1.4301, B: -0.0755 }), AnyApplies: Object.freeze({ A: 0.7114, B: 0.9073 }) })
+    })
+]);
+/**
+ * The answers with the Choice's confidence and the Likelihood calibrated for the exact model that
+ * gave them ({@link DECISION_DISCOVERY_CALIBRATION}), or null when that model has no discovery
+ * calibration. Other answers, and the Choice's distribution, are returned as they are.
+ *
+ * @param answers - The raw answers, by question key.
+ * @param answeredBy - The decision model that answered, and the model behind it.
+ */
+export function CalibrateDiscoveryAnswers(answers, answeredBy) {
+    const calibration = FindDecisionCalibration(DECISION_DISCOVERY_CALIBRATION, answeredBy);
+    if (!calibration) {
+        return null;
+    }
+    const calibrated = { ...answers };
+    const choice = answers[DECISION_DISCOVERY_AGENT_QUESTION];
+    if (choice?.Kind === 'Choice' && isFiniteNumber(choice.Confidence)) {
+        calibrated[DECISION_DISCOVERY_AGENT_QUESTION] = { ...choice, Confidence: ApplyPlattCalibration(choice.Confidence, calibration.Confidence) };
+    }
+    const applies = answers[DECISION_DISCOVERY_APPLIES_QUESTION];
+    if (applies?.Kind === 'Likelihood' && isFiniteNumber(applies.Probability)) {
+        calibrated[DECISION_DISCOVERY_APPLIES_QUESTION] = { ...applies, Probability: ApplyPlattCalibration(applies.Probability, calibration.AnyApplies) };
+    }
+    return calibrated;
+}
+/**
+ * The longest decision discovery may delay the run's first prompt. Past it the run moves on, the
+ * decision call is aborted, and nothing is injected.
+ */
+export const DECISION_DISCOVERY_TIMEOUT_MS = 1500;
+/**
+ * The fewest options discovery asks about. Below it nothing is asked and nothing is suggested.
+ *
+ * Two options are not enough, although the Choice is well-formed: its probabilities sum to 1, so its
+ * top answer is at least 0.5 however poorly both agents fit, and the any-applies Likelihood cannot
+ * vouch for them (see {@link DECISION_DISCOVERY_APPLIES_INSTRUCTIONS}). A confidence threshold then
+ * sits only a little above chance. The discovery eval (#4892) offered every request dozens of
+ * options, so this bound leaves the measured case alone. With fewer options the agent falls back to
+ * Find Candidate Agents, as it would without discovery.
+ */
+export const DECISION_DISCOVERY_MIN_OPTIONS = 3;
+/** The Choice's question key: which agent should handle the request. */
+export const DECISION_DISCOVERY_AGENT_QUESTION = 'agent';
+/** The Likelihood's question key: whether any of the agents should. */
+export const DECISION_DISCOVERY_APPLIES_QUESTION = 'anyApplies';
+/**
+ * The Likelihood's instructions. They stand on the request alone, because a driver may answer each
+ * question separately and never see the Choice's options.
+ *
+ * **Known limitation.** Because they name no agent, the Likelihood measures "is this specialist
+ * work?", not "does one of *these* agents fit?". A per-question driver, such as the Default
+ * Decision prompt's top-priority binding, answers each question on its own, so it never sees the
+ * options while answering this one. The Choice cannot say "none" either: its probabilities sum to
+ * 1 over the options it is given. So when the options leave out the agent the request needs (a host
+ * allow-list of a Billing and a Marketing agent, and a request for a legal review), both answers can
+ * still clear the threshold and suggest an agent that does not fit. The suggestion stays advisory,
+ * and the agent's prompt keeps the "unless the request clearly needs something else" escape.
+ *
+ * **Why the wording stays.** The discovery eval (#4892) measured, and the calibration (#4893)
+ * calibrated, exactly this question: its per-model Platt parameters and threshold hold only for this
+ * wording. Rewording it invalidates both, so the fix (quoting the options, or one Likelihood per
+ * option) waits for a re-measurement, tracked in #4938. Meanwhile {@link DECISION_DISCOVERY_MIN_OPTIONS} closes the
+ * worst case, two options, and leaves the measured case unchanged.
+ */
+export const DECISION_DISCOVERY_APPLIES_INSTRUCTIONS = 'This request asks for work that a specialist agent should do, rather than something the conversation manager should answer directly or plan as a multi-agent workflow.';
+/** The entity the semantic search ranks when the catalog is over the limit, as Find Candidate Agents does. */
+export const DECISION_DISCOVERY_SEARCH_ENTITY = 'MJ: AI Agents';
+/**
+ * The `ExecuteAgentParams.data` key holding the host's catalog of agents the conversation manager
+ * may route to (`ConversationAgentRunner` sets it, narrowed to the host's `AllowedAgentIDs`).
+ */
+export const DECISION_DISCOVERY_HOST_AGENTS_KEY = 'ALL_AVAILABLE_AGENTS';
+/** The most agent IDs the step records in a list, such as the agents left out for having no description. */
+export const DECISION_DISCOVERY_MAX_RECORDED_IDS = 50;
+/** A discovery that failed: nothing is injected. */
+export function FailedDecisionDiscovery(reason) {
+    return { Injected: false, Succeeded: false, Reason: reason };
+}
+/**
+ * Whether the `decisionDiscovery` setting is on in merged agent-type prompt params. Only `true` turns it
+ * on. Discovery runs only when the master switch, `decisionsEnabled`, is on as well: `BaseAgent` checks both.
+ */
+export function IsDecisionDiscoveryOn(promptParams) {
+    return promptParams?.decisionDiscovery === true;
+}
+/**
+ * Whether a run answers a conversation's opening request, the only turn discovery asks about: its
+ * messages hold exactly one user message. A follow-up turn carries the earlier requests in its
+ * history (or the summary of them, which also arrives as a user message), and may be continuing work
+ * with an agent already engaged, which a suggestion must not pull the agent away from. Assistant and
+ * system messages do not count, so a greeting before the first request still leaves it the opening
+ * turn. Read it from the messages the run started with, before the framework adds any.
+ *
+ * @param messages - The run's conversation messages, as the run received them.
+ */
+export function IsOpeningTurn(messages) {
+    return (messages ?? []).filter(m => m.role === 'user').length === 1;
+}
+/**
+ * Whether the request @mentions an agent other than the one running, in which case the user has
+ * already chosen and discovery does not run. It recognises both forms a mention takes by the time a
+ * run starts: the composer's `@{"_mode":"mention","type":"agent",...}` token, and the "@Agent Name"
+ * text `BaseAgent` converts that token to (or that the user typed). Names match whole, in any case.
+ * A mention of the running agent itself does not count: it names no one to delegate to.
+ *
+ * @param request - The run's opening request.
+ * @param agents - Every agent a mention could name.
+ * @param selfID - The running agent's ID.
+ */
+export function MentionsAgent(request, agents, selfID) {
+    if (!request.includes('@')) {
+        return false;
+    }
+    return mentionsAgentByToken(request, selfID)
+        || agents.some(a => !UUIDsEqual(a.ID, selfID) && mentionsByName(request, a.Name));
+}
+function mentionsAgentByToken(text, selfID) {
+    return ConversationUtility.ParseSpecialContent(text)
+        .some(token => isAgentMention(token.content) && !UUIDsEqual(token.content.id, selfID));
+}
+function isAgentMention(content) {
+    return content._mode !== 'form' && content._mode !== 'attachment' && content.type === 'agent';
+}
+/** Whether `text` holds "@" + `name` as a whole mention: not inside a word or an email address. */
+function mentionsByName(text, name) {
+    const needle = `@${(name ?? '').trim().toLowerCase()}`;
+    if (needle.length < 2) {
+        return false;
+    }
+    const haystack = text.toLowerCase();
+    for (let at = haystack.indexOf(needle); at >= 0; at = haystack.indexOf(needle, at + 1)) {
+        if (isMentionBoundary(haystack[at - 1]) && isMentionBoundary(haystack[at + needle.length])) {
+            return true;
+        }
+    }
+    return false;
+}
+function isMentionBoundary(character) {
+    return character === undefined || !/[\w@]/.test(character);
+}
+/**
+ * The Choice's options: one per agent with a description, in catalog order. An agent with a blank
+ * description is left out, because the decision model reads only descriptions and the decision
+ * primitive rejects an option without one.
+ */
+export function DecisionDiscoveryOptions(agents) {
+    return agents
+        .filter(a => hasDescription(a.Description))
+        .map(a => ({ ID: a.ID, Name: a.Name, Description: (a.Description ?? '').trim() }));
+}
+/** The IDs of the agents {@link DecisionDiscoveryOptions} leaves out for having a blank description, in catalog order. */
+export function AgentsWithoutDescription(agents) {
+    return agents.filter(a => !hasDescription(a.Description)).map(a => a.ID);
+}
+function hasDescription(description) {
+    return (description ?? '').trim().length > 0;
+}
+/**
+ * The agent IDs in the host's allow-list, when the run carries one: the `ID` of each entry of
+ * `data[`{@link DECISION_DISCOVERY_HOST_AGENTS_KEY}`]` when that is an array. `undefined` when it is
+ * absent or not an array. An empty array is an allow-list that allows no one.
+ */
+export function HostAllowedAgentIDs(data) {
+    const hostAgents = data?.[DECISION_DISCOVERY_HOST_AGENTS_KEY];
+    if (!Array.isArray(hostAgents)) {
+        return undefined;
+    }
+    return hostAgents
+        .map(entry => (IsPlainObject(entry) && typeof entry.ID === 'string' ? entry.ID : ''))
+        .filter(id => id.length > 0);
+}
+/**
+ * The agents the host allows, in their original order, compared UUID-safely. Without an allow-list
+ * every agent is kept, and `agents` itself is returned.
+ */
+export function KeepHostAllowedAgents(agents, allowedIDs) {
+    if (!allowedIDs) {
+        return agents;
+    }
+    const allowed = new Set(allowedIDs.map(id => NormalizeUUID(id)));
+    return agents.filter(a => allowed.has(NormalizeUUID(a.ID)));
+}
+/**
+ * The smallest option cap any of the decision prompt's models declares, or `undefined` when none
+ * does. The runner may answer with any of them after failover, so the smallest is the one they all
+ * accept. Anything but a positive number declares no cap.
+ */
+export function SmallestOptionCap(caps) {
+    const declared = caps.filter((cap) => typeof cap === 'number' && cap > 0);
+    return declared.length > 0 ? Math.min(...declared) : undefined;
+}
+/**
+ * The most options the Choice may offer: {@link DECISION_DISCOVERY_MAX_OPTIONS}, or the model's
+ * declared cap when that is smaller. It always applies, declared cap or not. More options than this
+ * are narrowed first.
+ */
+export function DecisionOptionLimit(declaredCap) {
+    return declaredCap === undefined ? DECISION_DISCOVERY_MAX_OPTIONS : Math.min(DECISION_DISCOVERY_MAX_OPTIONS, declaredCap);
+}
+/**
+ * Keeps the options the semantic search returned, in its rank order, up to `limit`. An option the
+ * search did not return is dropped, and a result that is not an option (an agent the user may not
+ * run, say) is skipped.
+ */
+export function RankOptionsBySearch(options, rankedIDs, limit) {
+    const byID = new Map(options.map(o => [NormalizeUUID(o.ID), o]));
+    const kept = [];
+    for (const id of rankedIDs) {
+        const option = byID.get(NormalizeUUID(id));
+        if (option && !kept.includes(option)) {
+            kept.push(option);
+        }
+        if (kept.length >= limit) {
+            break;
+        }
+    }
+    return kept;
+}
+/**
+ * The two questions, asked about the opening request in one call: a Choice over the options, whose
+ * values are agent IDs and whose descriptions are the agents' descriptions, and a Likelihood,
+ * {@link DECISION_DISCOVERY_APPLIES_INSTRUCTIONS}, that stands on the request alone.
+ *
+ * Neither can say that none of the options fits: the Likelihood never sees them, and the Choice's
+ * probabilities sum to 1 over them. The wording is what the discovery eval measured and calibrated,
+ * so it changes only with a re-measurement (see {@link DECISION_DISCOVERY_APPLIES_INSTRUCTIONS}).
+ *
+ * @param options - The agents to choose from.
+ */
+export function BuildDecisionDiscoveryQuestions(options) {
+    return {
+        [DECISION_DISCOVERY_AGENT_QUESTION]: {
+            Kind: 'Choice',
+            Instructions: 'Which agent should handle this request?',
+            Options: options.map(o => ({ Value: o.ID, Description: o.Description })),
+        },
+        [DECISION_DISCOVERY_APPLIES_QUESTION]: {
+            Kind: 'Likelihood',
+            Instructions: DECISION_DISCOVERY_APPLIES_INSTRUCTIONS,
+        },
+    };
+}
+/**
+ * Judges the answers. Confident means the Choice's confidence and the Likelihood both reach
+ * `minConfidence`. An answer that is missing, of the wrong kind, not a finite number, or names no
+ * option gives no answer at all.
+ */
+export function JudgeDecisionDiscovery(answers, options, minConfidence = DECISION_DISCOVERY_MIN_CONFIDENCE) {
+    const choice = answers?.[DECISION_DISCOVERY_AGENT_QUESTION];
+    const applies = answers?.[DECISION_DISCOVERY_APPLIES_QUESTION];
+    if (choice?.Kind !== 'Choice' || !isFiniteNumber(choice.Confidence)) {
+        return { Confident: false, Reason: `the '${DECISION_DISCOVERY_AGENT_QUESTION}' answer was missing or had no confidence` };
+    }
+    if (applies?.Kind !== 'Likelihood' || !isFiniteNumber(applies.Probability)) {
+        return { Confident: false, Reason: `the '${DECISION_DISCOVERY_APPLIES_QUESTION}' answer was missing or was not a probability` };
+    }
+    const agent = options.find(o => UUIDsEqual(o.ID, choice.Value));
+    if (!agent) {
+        return { Confident: false, Reason: `the '${DECISION_DISCOVERY_AGENT_QUESTION}' answer '${choice.Value}' is not one of the options` };
+    }
+    const answer = {
+        Agent: agent,
+        Confidence: choice.Confidence,
+        AnyApplies: applies.Probability,
+        Probabilities: probabilitiesByName(choice.Probabilities, options),
+    };
+    const shortfalls = [
+        choice.Confidence < minConfidence ? `the agent confidence ${choice.Confidence.toFixed(2)} is below ${minConfidence}` : '',
+        applies.Probability < minConfidence ? `the probability that any agent applies, ${applies.Probability.toFixed(2)}, is below ${minConfidence}` : '',
+    ].filter(s => s.length > 0);
+    return shortfalls.length === 0
+        ? { Answer: answer, Confident: true }
+        : { Answer: answer, Confident: false, Reason: shortfalls.join('; ') };
+}
+function isFiniteNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value);
+}
+function probabilitiesByName(probabilities, options) {
+    const byName = {};
+    for (const option of options) {
+        const probability = probabilities?.[option.ID];
+        if (typeof probability === 'number') {
+            byName[option.Name] = probability;
+        }
+    }
+    return byName;
+}
+/**
+ * What a finished decision call means for the prompt: the suggestion when both **calibrated**
+ * answers are confident, otherwise nothing, with the reason. A failed call, or an answer that cannot
+ * be used, is a failed discovery. An answer from a model with no discovery calibration is unsure.
+ */
+export function DecisionDiscoveryFromResult(result, options, minConfidence = DECISION_DISCOVERY_MIN_CONFIDENCE) {
+    if (!result.success) {
+        return { Injected: false, Succeeded: false, Reason: result.errorMessage || 'the decision call failed', Result: result };
+    }
+    const raw = JudgeDecisionDiscovery(result.Answers, options, minConfidence);
+    if (!raw.Answer) {
+        return { Injected: false, Succeeded: false, Reason: raw.Reason, Result: result };
+    }
+    const answeredBy = { ModelName: result.modelInfo?.modelName, ResolvedModel: result.DecisionResult?.ResolvedModel };
+    const calibrated = CalibrateDiscoveryAnswers(result.Answers, answeredBy);
+    if (!calibrated) {
+        const described = DescribeAnsweringModel(answeredBy);
+        const reason = `the answering model ${described} has no discovery calibration, so its answer is treated as unsure`;
+        return { Injected: false, Succeeded: true, Reason: reason, Answer: raw.Answer, Result: result, UncalibratedModel: described };
+    }
+    const verdict = JudgeDecisionDiscovery(calibrated, options, minConfidence);
+    if (!verdict.Answer) {
+        return { Injected: false, Succeeded: false, Reason: verdict.Reason, Result: result };
+    }
+    if (!verdict.Confident) {
+        return { Injected: false, Succeeded: true, Reason: verdict.Reason, Answer: verdict.Answer, Result: result };
+    }
+    return {
+        Injected: true,
+        Succeeded: true,
+        Message: SuggestedAgentMessage(verdict.Answer.Agent, verdict.Answer.Confidence),
+        Answer: verdict.Answer,
+        Result: result,
+    };
+}
+/** The system message placed before the first prompt when the answer is confident. */
+export function SuggestedAgentMessage(agent, confidence) {
+    return [
+        '<suggested_agent>',
+        `A typed decision over the agents you may delegate to chose: ${agent.Name} — ${agent.Description}`,
+        `(confidence ${confidence.toFixed(2)}). Delegate to it directly unless the request clearly needs something else.`,
+        '</suggested_agent>',
+    ].join('\n');
+}
+/**
+ * Whether a provider can run `SearchEntity`. It is declared on `IRunViewProvider`, which every real
+ * provider implements alongside `IMetadataProvider`.
+ */
+export function CanSearchEntities(provider) {
+    return !!provider && 'SearchEntity' in provider && typeof provider.SearchEntity === 'function';
+}
+/**
+ * The agents a user may run, as Find Candidate Agents filters them: through
+ * {@link AIAgentPermissionHelper.FilterRunnableAgents} (Active, with run permission), in catalog order.
+ *
+ * @param agents - The catalog: `AIEngine.Instance.Agents`.
+ * @param contextUser - The user whose run permission decides.
+ */
+export async function DecisionDiscoveryRunnableAgents(agents, contextUser) {
+    return AIAgentPermissionHelper.FilterRunnableAgents(agents, contextUser);
+}
+/**
+ * The agents this run may suggest: of the agents the user may run, the ones that can be discovered
+ * directly (the set Find Candidate Agents offers, through the same {@link AIAgentPermissionHelper}
+ * filter), minus the running agent itself. In catalog order.
+ *
+ * @param agents - The agents the user may run ({@link DecisionDiscoveryRunnableAgents}).
+ * @param runningAgentID - The agent running discovery.
+ */
+export function DecisionDiscoveryCatalog(agents, runningAgentID) {
+    return agents.filter(a => AIAgentPermissionHelper.IsDirectlyDiscoverable(a) && !UUIDsEqual(a.ID, runningAgentID));
+}
+/**
+ * The decision model's option cap: the smallest `Decision.MaxChoiceOptions` in the effective model
+ * configuration of the models the decision prompt is bound to, the setting `AIDecisionRunner`
+ * checks before its call. `undefined` when none declares one, or the prompt is not found.
+ *
+ * @param engine - The loaded engine: `AIEngine.Instance`.
+ * @param promptName - The decision prompt's name, matched whole in any case.
+ */
+export function DecisionPromptOptionCap(engine, promptName) {
+    const target = promptName.trim().toLowerCase();
+    const prompt = engine.Prompts.find(p => (p.Name ?? '').trim().toLowerCase() === target);
+    if (!prompt) {
+        return undefined;
+    }
+    const caps = engine.PromptModels
+        .filter(pm => UUIDsEqual(pm.PromptID, prompt.ID) && (pm.Status === 'Active' || pm.Status === 'Preview'))
+        .map(pm => {
+        const modelVendor = pm.VendorID
+            ? engine.ModelVendors.find(mv => UUIDsEqual(mv.ModelID, pm.ModelID) && UUIDsEqual(mv.VendorID, pm.VendorID))
+            : undefined;
+        return engine.GetEffectiveModelConfiguration(pm.ModelID, modelVendor?.ID)?.Decision?.MaxChoiceOptions;
+    });
+    return SmallestOptionCap(caps);
+}
+/**
+ * The search Find Candidate Agents runs, for one request: hybrid over
+ * {@link DECISION_DISCOVERY_SEARCH_ENTITY}. Its similarity floor is not applied: the caller judges fit.
+ *
+ * @param provider - A provider that can search ({@link CanSearchEntities}).
+ * @param request - The request to rank agents for.
+ * @param contextUser - The user the search runs as.
+ */
+export function DecisionDiscoveryAgentSearch(provider, request, contextUser) {
+    return topK => provider.SearchEntity({
+        entityName: DECISION_DISCOVERY_SEARCH_ENTITY,
+        searchText: request,
+        options: { mode: 'hybrid', topK, minScore: 0, contextUser },
+    });
+}
+/**
+ * The Choice's options, rebuilt on every call and never cached: the agents in the permitted
+ * catalog ({@link DecisionDiscoveryCatalog}) that the host allows and that have a description.
+ * There are never more than {@link DecisionOptionLimit}: when there are, the semantic search narrows
+ * them first; if it cannot, `Error` says why.
+ *
+ * @param params - The permitted agents, the running agent, the host's allow-list, the option cap and the search.
+ */
+export async function BuildDecisionDiscoveryOptionSet(params) {
+    const catalog = KeepHostAllowedAgents(DecisionDiscoveryCatalog(params.Agents, params.RunningAgentID), params.HostAllowedIDs);
+    const options = DecisionDiscoveryOptions(catalog);
+    const limit = DecisionOptionLimit(params.DeclaredCap);
+    const set = {
+        Options: options,
+        CatalogSize: catalog.length,
+        HostAllowListSize: params.HostAllowedIDs?.length,
+        WithoutDescription: AgentsWithoutDescription(catalog),
+        OptionLimit: limit,
+        DeclaredOptionCap: params.DeclaredCap,
+    };
+    if (options.length <= limit) {
+        return set;
+    }
+    if (!params.Search) {
+        return { ...set, Options: [], NarrowedFrom: options.length,
+            Error: `${options.length} agents exceed the limit of ${limit} options, and the provider cannot run the semantic search that narrows them` };
+    }
+    // Over-fetching threefold for the permission filter, as Find Candidate Agents does.
+    const results = await params.Search(limit * 3);
+    return { ...set, Options: RankOptionsBySearch(options, results.map(r => r.recordId), limit), NarrowedFrom: options.length };
+}
+//# sourceMappingURL=decision-discovery.js.map

package/dist/decision-discovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decision-discovery.js","sourceRoot":"","sources":["../src/decision-discovery.ts"],"names":[],"mappings":"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"}

package/dist/finish-if-mode-warnings.d.ts

@@ -0,0 +1,39 @@
+/** The most characters of a `finishIfMode` value that is not a mode a warning shows. */
+export declare const FINISH_IF_MODE_WARNING_SHOWN_MAX = 100;
+/** The most agent and value pairs {@link FinishIfModeWarnings} remembers as already reported. */
+export declare const FINISH_IF_MODE_WARNINGS_REMEMBERED = 1000;
+/**
+ * Decides when to warn that an agent's merged `finishIfMode` is set but is not one of the
+ * {@link FINISH_IF_MODES}: once per agent and value. `ResolveFinishIfMode` treats such a value as
+ * `'off'`, so without the warning a typo such as `"On"` or `"true"` would turn the agent's gates
+ * off without a word.
+ *
+ * The value can come from whoever starts a run, through its runtime prompt-param overrides, so
+ * both what is logged and what is remembered are bounded:
+ * - a warning shows at most {@link FINISH_IF_MODE_WARNING_SHOWN_MAX} characters of the value, and
+ *   notes its full length when it is longer;
+ * - two values count as the same when their warnings would read the same, so a pair is
+ *   remembered by a key of bounded size;
+ * - at most `maxRemembered` pairs are remembered, and the one seen least recently is dropped
+ *   first. A dropped pair warns again the next time it is seen, which is harmless.
+ */
+export declare class FinishIfModeWarnings {
+    private readonly reported;
+    constructor(maxRemembered?: number);
+    /** How many agent and value pairs are remembered as reported. Never more than {@link MaxRemembered}. */
+    get Remembered(): number;
+    /** The most agent and value pairs remembered at once. */
+    get MaxRemembered(): number;
+    /**
+     * The warning to log for an agent's merged `finishIfMode`, or `undefined` when there is none
+     * to log: the value is absent, is a mode, or was reported for this agent already.
+     */
+    WarningFor(agentID: string, agentName: string, value: unknown): string | undefined;
+}
+/**
+ * A `finishIfMode` value as its warning shows it. A string keeps its quotes, so `"true"` and
+ * `true` read differently. Anything else is shown as JSON. Either is cut to
+ * {@link FINISH_IF_MODE_WARNING_SHOWN_MAX} characters, and a longer one notes its full length.
+ */
+export declare function ShowFinishIfModeValue(value: unknown): string;
+//# sourceMappingURL=finish-if-mode-warnings.d.ts.map

package/dist/finish-if-mode-warnings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"finish-if-mode-warnings.d.ts","sourceRoot":"","sources":["../src/finish-if-mode-warnings.ts"],"names":[],"mappings":"AAGA,wFAAwF;AACxF,eAAO,MAAM,gCAAgC,MAAM,CAAC;AAEpD,iGAAiG;AACjG,eAAO,MAAM,kCAAkC,OAAO,CAAC;AAEvD;;;;;;;;;;;;;;GAcG;AACH,qBAAa,oBAAoB;IAC7B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA2B;gBAExC,aAAa,GAAE,MAA2C;IAItE,wGAAwG;IACxG,IAAW,UAAU,IAAI,MAAM,CAE9B;IAED,yDAAyD;IACzD,IAAW,aAAa,IAAI,MAAM,CAEjC;IAED;;;OAGG;IACI,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS;CAc5F;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAU5D"}

package/dist/finish-if-mode-warnings.js

@@ -0,0 +1,78 @@
+import { MJLruCache } from '@memberjunction/global';
+import { FINISH_IF_MODES, IsFinishIfMode } from './agent-types/loop-agent-prompt-params.js';
+/** The most characters of a `finishIfMode` value that is not a mode a warning shows. */
+export const FINISH_IF_MODE_WARNING_SHOWN_MAX = 100;
+/** The most agent and value pairs {@link FinishIfModeWarnings} remembers as already reported. */
+export const FINISH_IF_MODE_WARNINGS_REMEMBERED = 1000;
+/**
+ * Decides when to warn that an agent's merged `finishIfMode` is set but is not one of the
+ * {@link FINISH_IF_MODES}: once per agent and value. `ResolveFinishIfMode` treats such a value as
+ * `'off'`, so without the warning a typo such as `"On"` or `"true"` would turn the agent's gates
+ * off without a word.
+ *
+ * The value can come from whoever starts a run, through its runtime prompt-param overrides, so
+ * both what is logged and what is remembered are bounded:
+ * - a warning shows at most {@link FINISH_IF_MODE_WARNING_SHOWN_MAX} characters of the value, and
+ *   notes its full length when it is longer;
+ * - two values count as the same when their warnings would read the same, so a pair is
+ *   remembered by a key of bounded size;
+ * - at most `maxRemembered` pairs are remembered, and the one seen least recently is dropped
+ *   first. A dropped pair warns again the next time it is seen, which is harmless.
+ */
+export class FinishIfModeWarnings {
+    constructor(maxRemembered = FINISH_IF_MODE_WARNINGS_REMEMBERED) {
+        this.reported = new MJLruCache({ maxSize: maxRemembered });
+    }
+    /** How many agent and value pairs are remembered as reported. Never more than {@link MaxRemembered}. */
+    get Remembered() {
+        return this.reported.Size;
+    }
+    /** The most agent and value pairs remembered at once. */
+    get MaxRemembered() {
+        return this.reported.MaxSize;
+    }
+    /**
+     * The warning to log for an agent's merged `finishIfMode`, or `undefined` when there is none
+     * to log: the value is absent, is a mode, or was reported for this agent already.
+     */
+    WarningFor(agentID, agentName, value) {
+        if (value === undefined || value === null || IsFinishIfMode(value)) {
+            return undefined;
+        }
+        const shown = ShowFinishIfModeValue(value);
+        const key = `${agentID}\u0000${shown}`;
+        // Get also marks the pair as recently seen, so a value an agent keeps sending is not dropped.
+        if (this.reported.Get(key)) {
+            return undefined;
+        }
+        this.reported.Set(key, true);
+        const modes = FINISH_IF_MODES.map(mode => `'${mode}'`).join(', ');
+        return `Agent '${agentName}' has finishIfMode ${shown}, which is not one of ${modes}, so its finishIf gates are off. Mode names are case-sensitive.`;
+    }
+}
+/**
+ * A `finishIfMode` value as its warning shows it. A string keeps its quotes, so `"true"` and
+ * `true` read differently. Anything else is shown as JSON. Either is cut to
+ * {@link FINISH_IF_MODE_WARNING_SHOWN_MAX} characters, and a longer one notes its full length.
+ */
+export function ShowFinishIfModeValue(value) {
+    if (typeof value === 'string') {
+        // Cut before quoting, so a huge string is never copied whole.
+        const cut = value.slice(0, FINISH_IF_MODE_WARNING_SHOWN_MAX);
+        return value.length > cut.length ? `${JSON.stringify(cut)}… (${value.length} characters)` : JSON.stringify(cut);
+    }
+    const json = jsonOf(value);
+    return json.length > FINISH_IF_MODE_WARNING_SHOWN_MAX
+        ? `${json.slice(0, FINISH_IF_MODE_WARNING_SHOWN_MAX)}… (${json.length} characters as JSON)`
+        : json;
+}
+/** A value as JSON, or as `String(value)` when it cannot be written as JSON. */
+function jsonOf(value) {
+    try {
+        return JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+//# sourceMappingURL=finish-if-mode-warnings.js.map