@memberjunction/ng-conversations 6.2.0-edge.5 → 6.2.0-edge.7

package/dist/lib/utils/agent-handoff-map.js

@@ -0,0 +1,270 @@
+import { LogError, RunView } from '@memberjunction/core';
+import { AIEngineBase } from '@memberjunction/ai-engine-base';
+import { CleanAndParseJSON, EscapeSQLString, IndexByUUID, NormalizeUUID, UUIDsEqual, } from '@memberjunction/global';
+export const HANDOFF_STEP_FIELDS = [
+    'ID',
+    'AgentRunID',
+    'StepNumber',
+    'StepName',
+    'StepType',
+    'Status',
+    'TargetID',
+    'InputData',
+    'OutputData',
+    'ErrorMessage',
+];
+/**
+ * Loads `MJ: AI Agent Run Steps` rows with `StepType = 'Handoff'` for the given run IDs
+ * in a single `RunView` query (`ResultType: 'simple'`, explicit `Fields`).
+ */
+export async function LoadHandoffStepsForRuns(provider, runIds) {
+    const uniqueIds = Array.from(new Set(runIds.map(id => id?.trim()).filter((id) => !!id)));
+    if (uniqueIds.length === 0) {
+        return [];
+    }
+    try {
+        const rv = RunView.FromMetadataProvider(provider);
+        const quotedIds = uniqueIds.map(id => `'${EscapeSQLString(id)}'`).join(',');
+        const result = await rv.RunView({
+            EntityName: 'MJ: AI Agent Run Steps',
+            ExtraFilter: `StepType = 'Handoff' AND AgentRunID IN (${quotedIds})`,
+            Fields: HANDOFF_STEP_FIELDS,
+            OrderBy: 'StepNumber ASC',
+            ResultType: 'simple',
+        });
+        if (!result?.Success || !result.Results) {
+            LogError(`LoadHandoffStepsForRuns failed: ${result?.ErrorMessage ?? 'Unknown RunView error'}`);
+            return [];
+        }
+        return result.Results;
+    }
+    catch (error) {
+        LogError('LoadHandoffStepsForRuns threw an error:', undefined, error);
+        return [];
+    }
+}
+function parseJsonSafe(raw) {
+    if (!raw || !raw.trim()) {
+        return null;
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return CleanAndParseJSON(raw, false);
+    }
+}
+function resolveParticipant(agentId, fallbackName, agents) {
+    const agentsById = IndexByUUID(agents);
+    const match = agentId
+        ? agentsById.Get(agentId)
+        : fallbackName
+            ? agents.find(a => a.Name?.trim().toLowerCase() === fallbackName.trim().toLowerCase())
+            : undefined;
+    if (match) {
+        return {
+            ID: match.ID,
+            Name: match.Name || fallbackName || 'Agent',
+            AvatarUrl: match.LogoURL || null,
+            IconClass: match.IconClass || null,
+        };
+    }
+    return {
+        ID: agentId ?? null,
+        Name: fallbackName?.trim() || 'Agent',
+        AvatarUrl: null,
+        IconClass: null,
+    };
+}
+/**
+ * Looks up a `MessageHandoffInfo` in a detail-ID map using case-insensitive UUID matching.
+ */
+export function LookupHandoffByDetailId(map, detailId) {
+    if (!map || !detailId) {
+        return null;
+    }
+    const direct = map.get(detailId) ?? map.get(NormalizeUUID(detailId));
+    if (direct) {
+        return direct;
+    }
+    for (const [key, value] of map.entries()) {
+        if (UUIDsEqual(key, detailId)) {
+            return value;
+        }
+    }
+    return null;
+}
+/**
+ * Finds the target detail row in `messages` for a handoff originating from `sourceDetailId`.
+ */
+export function FindHandoffTargetDetail(sourceDetailId, targetAgentId, messages) {
+    return messages.find(m => m.Role === 'AI' &&
+        !UUIDsEqual(m.ID, sourceDetailId) &&
+        UUIDsEqual(m.ParentID, sourceDetailId) &&
+        (!targetAgentId || !m.AgentID || UUIDsEqual(m.AgentID, targetAgentId)));
+}
+/**
+ * Computes the effective `Status` of a handoff given the current loaded `messages`.
+ */
+export function DeriveHandoffStatus(baseStatus, sourceDetailId, targetAgentId, targetDetailId, messages) {
+    if (baseStatus === 'Failed') {
+        return 'Failed';
+    }
+    const targetDetail = targetDetailId
+        ? messages.find(m => UUIDsEqual(m.ID, targetDetailId)) ??
+            FindHandoffTargetDetail(sourceDetailId, targetAgentId, messages)
+        : FindHandoffTargetDetail(sourceDetailId, targetAgentId, messages);
+    if (!targetDetail || targetDetail.Status === 'In-Progress') {
+        return 'Transferring';
+    }
+    return 'Transferred';
+}
+/**
+ * Builds the `HandoffsByDetailId` map from loaded messages, agent runs, and `Handoff` run steps.
+ */
+export function BuildHandoffsByDetailId(params) {
+    const { Messages: messages, AgentRunsByDetailId: agentRunsByDetailId, HandoffSteps: handoffSteps, Agents: agents, Presets: presets = [], } = params;
+    const result = new Map();
+    if (handoffSteps.length === 0 || agentRunsByDetailId.size === 0) {
+        return result;
+    }
+    const stepsByRunKey = new Map();
+    for (const step of handoffSteps) {
+        if (!step.AgentRunID)
+            continue;
+        if (step.StepType && step.StepType !== 'Handoff')
+            continue;
+        const key = NormalizeUUID(step.AgentRunID);
+        const list = stepsByRunKey.get(key) ?? [];
+        list.push(step);
+        stepsByRunKey.set(key, list);
+    }
+    for (const list of stepsByRunKey.values()) {
+        list.sort((a, b) => (a.StepNumber ?? 0) - (b.StepNumber ?? 0));
+    }
+    const messagesById = IndexByUUID(messages);
+    const presetsById = IndexByUUID(presets);
+    const defaultPresetsByAgentKey = new Map();
+    for (const p of presets) {
+        if (p.Status === 'Active' && p.IsDefault && p.AgentID) {
+            const key = NormalizeUUID(p.AgentID);
+            if (!defaultPresetsByAgentKey.has(key)) {
+                defaultPresetsByAgentKey.set(key, p);
+            }
+        }
+    }
+    for (const [detailId, agentRun] of agentRunsByDetailId.entries()) {
+        const runSteps = stepsByRunKey.get(NormalizeUUID(agentRun.ID));
+        if (!runSteps || runSteps.length === 0) {
+            continue;
+        }
+        const completedSteps = runSteps.filter(s => s.Status === 'Completed');
+        const chosenStep = completedSteps.length > 0
+            ? completedSteps[completedSteps.length - 1]
+            : runSteps[runSteps.length - 1];
+        const isFailed = chosenStep.Status === 'Failed' && completedSteps.length === 0;
+        const input = parseJsonSafe(chosenStep.InputData);
+        const output = parseJsonSafe(chosenStep.OutputData);
+        const sourceDetail = messagesById.Get(detailId);
+        const sourceAgentId = sourceDetail?.AgentID || agentRun.AgentID || null;
+        const sourceFallbackName = sourceDetail?.Agent || agentRun.Agent || 'Sage';
+        const sourceParticipant = resolveParticipant(sourceAgentId, sourceFallbackName, agents);
+        const targetAgentId = chosenStep.TargetID || output?.HandoffToAgentID || null;
+        const targetFallbackName = output?.TargetAgentName ||
+            output?.AgentName ||
+            input?.agentName ||
+            chosenStep.StepName?.replace(/^Handoff:\s*/i, '').trim() ||
+            'Agent';
+        const targetParticipant = resolveParticipant(targetAgentId, targetFallbackName, agents);
+        const explicitTargetDetailId = output?.TargetConversationDetailID ?? null;
+        const targetDetail = isFailed
+            ? undefined
+            : (explicitTargetDetailId ? messagesById.Get(explicitTargetDetailId) : undefined) ??
+                FindHandoffTargetDetail(detailId, targetParticipant.ID, messages);
+        const resolvedTargetDetailId = targetDetail?.ID ?? explicitTargetDetailId ?? null;
+        const status = isFailed
+            ? 'Failed'
+            : DeriveHandoffStatus('Transferred', detailId, targetParticipant.ID, resolvedTargetDetailId, messages);
+        let presetName = null;
+        if (!isFailed) {
+            if (output?.PresetName?.trim()) {
+                presetName = output.PresetName.trim();
+            }
+            else if (output?.PresetID) {
+                const matchedPreset = presetsById.Get(output.PresetID);
+                presetName = matchedPreset?.DisplayName || matchedPreset?.Name || null;
+            }
+            else if (targetParticipant.ID) {
+                const defaultPreset = defaultPresetsByAgentKey.get(NormalizeUUID(targetParticipant.ID)) ??
+                    AIEngineBase.Instance.GetDefaultAgentConfigurationPreset(targetParticipant.ID);
+                presetName = defaultPreset?.DisplayName || defaultPreset?.Name || null;
+            }
+        }
+        const brief = output?.Brief ?? input?.brief ?? null;
+        const reason = output?.Reason ?? input?.reason ?? null;
+        const failureReason = isFailed
+            ? output?.RefusalReason || chosenStep.ErrorMessage || 'Transfer could not complete'
+            : null;
+        let hopChain = null;
+        if (Array.isArray(output?.Chain) && output.Chain.length >= 2) {
+            const chainParticipants = output.Chain.map(hopAgentId => resolveParticipant(hopAgentId, null, agents));
+            chainParticipants.push(targetParticipant);
+            hopChain = chainParticipants;
+        }
+        result.set(detailId, {
+            SourceAgent: sourceParticipant,
+            TargetAgent: targetParticipant,
+            PresetName: presetName,
+            Brief: brief,
+            Reason: reason,
+            Status: status,
+            FailureReason: failureReason,
+            HopChain: hopChain,
+            TargetDetailId: resolvedTargetDetailId,
+        });
+    }
+    return result;
+}
+/**
+ * Resolves `MessageHandedOffFromInfo` for a target message row when its parent row handed off to it.
+ */
+export function ResolveHandedOffFromForMessage(message, handoffsByDetailId) {
+    if (!handoffsByDetailId || handoffsByDetailId.size === 0 || message.Role !== 'AI') {
+        return null;
+    }
+    if (message.ParentID) {
+        const parentHandoff = LookupHandoffByDetailId(handoffsByDetailId, message.ParentID);
+        if (parentHandoff &&
+            parentHandoff.Status !== 'Failed' &&
+            (!parentHandoff.TargetAgent.ID ||
+                !message.AgentID ||
+                UUIDsEqual(parentHandoff.TargetAgent.ID, message.AgentID))) {
+            return {
+                SourceAgent: parentHandoff.SourceAgent,
+                TargetAgent: parentHandoff.TargetAgent,
+                PresetName: parentHandoff.PresetName ?? null,
+                Brief: parentHandoff.Brief ?? null,
+                Reason: parentHandoff.Reason ?? null,
+                HopChain: parentHandoff.HopChain ?? null,
+                SourceDetailId: message.ParentID,
+            };
+        }
+    }
+    for (const [sourceDetailId, handoff] of handoffsByDetailId.entries()) {
+        if (handoff.Status !== 'Failed' &&
+            handoff.TargetDetailId &&
+            UUIDsEqual(handoff.TargetDetailId, message.ID)) {
+            return {
+                SourceAgent: handoff.SourceAgent,
+                TargetAgent: handoff.TargetAgent,
+                PresetName: handoff.PresetName ?? null,
+                Brief: handoff.Brief ?? null,
+                Reason: handoff.Reason ?? null,
+                HopChain: handoff.HopChain ?? null,
+                SourceDetailId: sourceDetailId,
+            };
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=agent-handoff-map.js.map

package/dist/lib/utils/agent-handoff-map.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-handoff-map.js","sourceRoot":"","sources":["../../../src/lib/utils/agent-handoff-map.ts"],"names":[],"mappings":"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","sourcesContent":["import { IMetadataProvider, LogError, RunView } from '@memberjunction/core';\nimport {\n  MJConversationDetailEntity,\n  MJAIAgentConfigurationEntity,\n} from '@memberjunction/core-entities';\nimport {\n  MJAIAgentEntityExtended,\n  MJAIAgentRunEntityExtended,\n} from '@memberjunction/ai-core-plus';\nimport { AIEngineBase } from '@memberjunction/ai-engine-base';\nimport {\n  CleanAndParseJSON,\n  EscapeSQLString,\n  IndexByUUID,\n  NormalizeUUID,\n  UUIDsEqual,\n} from '@memberjunction/global';\nimport {\n  AgentHandoffParticipant,\n  AgentHandoffStatus,\n  MessageHandedOffFromInfo,\n  MessageHandoffInfo,\n} from '../components/message/agent-handoff-card.component';\n\n/**\n * Simple row shape projected from `MJ: AI Agent Run Steps` for `StepType = 'Handoff'`.\n */\nexport interface HandoffRunStepRow {\n  ID: string;\n  AgentRunID: string;\n  StepNumber?: number | null;\n  StepName?: string | null;\n  StepType?: string | null;\n  Status?: string | null;\n  TargetID?: string | null;\n  InputData?: string | null;\n  OutputData?: string | null;\n  ErrorMessage?: string | null;\n}\n\ninterface ParsedHandoffInput {\n  agentName?: string;\n  brief?: string;\n  reason?: string;\n}\n\ninterface ParsedHandoffOutput {\n  HandoffToAgentID?: string;\n  TargetAgentName?: string;\n  AgentName?: string;\n  TargetConversationDetailID?: string | null;\n  PresetID?: string | null;\n  PresetName?: string | null;\n  PresetSource?: string | null;\n  Brief?: string;\n  Reason?: string;\n  RefusalReason?: string;\n  Hop?: number;\n  Chain?: string[];\n}\n\nexport const HANDOFF_STEP_FIELDS: string[] = [\n  'ID',\n  'AgentRunID',\n  'StepNumber',\n  'StepName',\n  'StepType',\n  'Status',\n  'TargetID',\n  'InputData',\n  'OutputData',\n  'ErrorMessage',\n];\n\n/**\n * Loads `MJ: AI Agent Run Steps` rows with `StepType = 'Handoff'` for the given run IDs\n * in a single `RunView` query (`ResultType: 'simple'`, explicit `Fields`).\n */\nexport async function LoadHandoffStepsForRuns(\n  provider: IMetadataProvider,\n  runIds: readonly string[]\n): Promise<HandoffRunStepRow[]> {\n  const uniqueIds = Array.from(\n    new Set(runIds.map(id => id?.trim()).filter((id): id is string => !!id))\n  );\n  if (uniqueIds.length === 0) {\n    return [];\n  }\n  try {\n    const rv = RunView.FromMetadataProvider(provider);\n    const quotedIds = uniqueIds.map(id => `'${EscapeSQLString(id)}'`).join(',');\n    const result = await rv.RunView<HandoffRunStepRow>({\n      EntityName: 'MJ: AI Agent Run Steps',\n      ExtraFilter: `StepType = 'Handoff' AND AgentRunID IN (${quotedIds})`,\n      Fields: HANDOFF_STEP_FIELDS,\n      OrderBy: 'StepNumber ASC',\n      ResultType: 'simple',\n    });\n    if (!result?.Success || !result.Results) {\n      LogError(`LoadHandoffStepsForRuns failed: ${result?.ErrorMessage ?? 'Unknown RunView error'}`);\n      return [];\n    }\n    return result.Results;\n  } catch (error) {\n    LogError('LoadHandoffStepsForRuns threw an error:', undefined, error);\n    return [];\n  }\n}\n\nfunction parseJsonSafe<T>(raw: string | null | undefined): T | null {\n  if (!raw || !raw.trim()) {\n    return null;\n  }\n  try {\n    return JSON.parse(raw) as T;\n  } catch {\n    return CleanAndParseJSON<T>(raw, false);\n  }\n}\n\nfunction resolveParticipant(\n  agentId: string | null | undefined,\n  fallbackName: string | null | undefined,\n  agents: readonly MJAIAgentEntityExtended[]\n): AgentHandoffParticipant {\n  const agentsById = IndexByUUID(agents);\n  const match = agentId\n    ? agentsById.Get(agentId)\n    : fallbackName\n      ? agents.find(a => a.Name?.trim().toLowerCase() === fallbackName.trim().toLowerCase())\n      : undefined;\n\n  if (match) {\n    return {\n      ID: match.ID,\n      Name: match.Name || fallbackName || 'Agent',\n      AvatarUrl: match.LogoURL || null,\n      IconClass: match.IconClass || null,\n    };\n  }\n  return {\n    ID: agentId ?? null,\n    Name: fallbackName?.trim() || 'Agent',\n    AvatarUrl: null,\n    IconClass: null,\n  };\n}\n\n/**\n * Looks up a `MessageHandoffInfo` in a detail-ID map using case-insensitive UUID matching.\n */\nexport function LookupHandoffByDetailId(\n  map: ReadonlyMap<string, MessageHandoffInfo> | null | undefined,\n  detailId: string | null | undefined\n): MessageHandoffInfo | null {\n  if (!map || !detailId) {\n    return null;\n  }\n  const direct = map.get(detailId) ?? map.get(NormalizeUUID(detailId));\n  if (direct) {\n    return direct;\n  }\n  for (const [key, value] of map.entries()) {\n    if (UUIDsEqual(key, detailId)) {\n      return value;\n    }\n  }\n  return null;\n}\n\n/**\n * Finds the target detail row in `messages` for a handoff originating from `sourceDetailId`.\n */\nexport function FindHandoffTargetDetail(\n  sourceDetailId: string,\n  targetAgentId: string | null | undefined,\n  messages: readonly MJConversationDetailEntity[]\n): MJConversationDetailEntity | undefined {\n  return messages.find(\n    m =>\n      m.Role === 'AI' &&\n      !UUIDsEqual(m.ID, sourceDetailId) &&\n      UUIDsEqual(m.ParentID, sourceDetailId) &&\n      (!targetAgentId || !m.AgentID || UUIDsEqual(m.AgentID, targetAgentId))\n  );\n}\n\n/**\n * Computes the effective `Status` of a handoff given the current loaded `messages`.\n */\nexport function DeriveHandoffStatus(\n  baseStatus: AgentHandoffStatus,\n  sourceDetailId: string,\n  targetAgentId: string | null | undefined,\n  targetDetailId: string | null | undefined,\n  messages: readonly MJConversationDetailEntity[]\n): AgentHandoffStatus {\n  if (baseStatus === 'Failed') {\n    return 'Failed';\n  }\n  const targetDetail = targetDetailId\n    ? messages.find(m => UUIDsEqual(m.ID, targetDetailId)) ??\n      FindHandoffTargetDetail(sourceDetailId, targetAgentId, messages)\n    : FindHandoffTargetDetail(sourceDetailId, targetAgentId, messages);\n  if (!targetDetail || targetDetail.Status === 'In-Progress') {\n    return 'Transferring';\n  }\n  return 'Transferred';\n}\n\n/**\n * Builds the `HandoffsByDetailId` map from loaded messages, agent runs, and `Handoff` run steps.\n */\nexport function BuildHandoffsByDetailId(params: {\n  Messages: readonly MJConversationDetailEntity[];\n  AgentRunsByDetailId: ReadonlyMap<string, MJAIAgentRunEntityExtended>;\n  HandoffSteps: readonly HandoffRunStepRow[];\n  Agents: readonly MJAIAgentEntityExtended[];\n  Presets?: readonly MJAIAgentConfigurationEntity[];\n}): Map<string, MessageHandoffInfo> {\n  const {\n    Messages: messages,\n    AgentRunsByDetailId: agentRunsByDetailId,\n    HandoffSteps: handoffSteps,\n    Agents: agents,\n    Presets: presets = [],\n  } = params;\n\n  const result = new Map<string, MessageHandoffInfo>();\n  if (handoffSteps.length === 0 || agentRunsByDetailId.size === 0) {\n    return result;\n  }\n\n  const stepsByRunKey = new Map<string, HandoffRunStepRow[]>();\n  for (const step of handoffSteps) {\n    if (!step.AgentRunID) continue;\n    if (step.StepType && step.StepType !== 'Handoff') continue;\n    const key = NormalizeUUID(step.AgentRunID);\n    const list = stepsByRunKey.get(key) ?? [];\n    list.push(step);\n    stepsByRunKey.set(key, list);\n  }\n\n  for (const list of stepsByRunKey.values()) {\n    list.sort((a, b) => (a.StepNumber ?? 0) - (b.StepNumber ?? 0));\n  }\n\n  const messagesById = IndexByUUID(messages);\n  const presetsById = IndexByUUID(presets);\n  const defaultPresetsByAgentKey = new Map<string, MJAIAgentConfigurationEntity>();\n  for (const p of presets) {\n    if (p.Status === 'Active' && p.IsDefault && p.AgentID) {\n      const key = NormalizeUUID(p.AgentID);\n      if (!defaultPresetsByAgentKey.has(key)) {\n        defaultPresetsByAgentKey.set(key, p);\n      }\n    }\n  }\n\n  for (const [detailId, agentRun] of agentRunsByDetailId.entries()) {\n    const runSteps = stepsByRunKey.get(NormalizeUUID(agentRun.ID));\n    if (!runSteps || runSteps.length === 0) {\n      continue;\n    }\n\n    const completedSteps = runSteps.filter(s => s.Status === 'Completed');\n    const chosenStep =\n      completedSteps.length > 0\n        ? completedSteps[completedSteps.length - 1]\n        : runSteps[runSteps.length - 1];\n\n    const isFailed = chosenStep.Status === 'Failed' && completedSteps.length === 0;\n    const input = parseJsonSafe<ParsedHandoffInput>(chosenStep.InputData);\n    const output = parseJsonSafe<ParsedHandoffOutput>(chosenStep.OutputData);\n\n    const sourceDetail = messagesById.Get(detailId);\n    const sourceAgentId = sourceDetail?.AgentID || agentRun.AgentID || null;\n    const sourceFallbackName = sourceDetail?.Agent || agentRun.Agent || 'Sage';\n    const sourceParticipant = resolveParticipant(sourceAgentId, sourceFallbackName, agents);\n\n    const targetAgentId =\n      chosenStep.TargetID || output?.HandoffToAgentID || null;\n    const targetFallbackName =\n      output?.TargetAgentName ||\n      output?.AgentName ||\n      input?.agentName ||\n      chosenStep.StepName?.replace(/^Handoff:\\s*/i, '').trim() ||\n      'Agent';\n    const targetParticipant = resolveParticipant(targetAgentId, targetFallbackName, agents);\n\n    const explicitTargetDetailId = output?.TargetConversationDetailID ?? null;\n    const targetDetail = isFailed\n      ? undefined\n      : (explicitTargetDetailId ? messagesById.Get(explicitTargetDetailId) : undefined) ??\n        FindHandoffTargetDetail(detailId, targetParticipant.ID, messages);\n\n    const resolvedTargetDetailId = targetDetail?.ID ?? explicitTargetDetailId ?? null;\n\n    const status: AgentHandoffStatus = isFailed\n      ? 'Failed'\n      : DeriveHandoffStatus(\n          'Transferred',\n          detailId,\n          targetParticipant.ID,\n          resolvedTargetDetailId,\n          messages\n        );\n\n    let presetName: string | null = null;\n    if (!isFailed) {\n      if (output?.PresetName?.trim()) {\n        presetName = output.PresetName.trim();\n      } else if (output?.PresetID) {\n        const matchedPreset = presetsById.Get(output.PresetID);\n        presetName = matchedPreset?.DisplayName || matchedPreset?.Name || null;\n      } else if (targetParticipant.ID) {\n        const defaultPreset =\n          defaultPresetsByAgentKey.get(NormalizeUUID(targetParticipant.ID)) ??\n          AIEngineBase.Instance.GetDefaultAgentConfigurationPreset(targetParticipant.ID);\n        presetName = defaultPreset?.DisplayName || defaultPreset?.Name || null;\n      }\n    }\n\n    const brief = output?.Brief ?? input?.brief ?? null;\n    const reason = output?.Reason ?? input?.reason ?? null;\n    const failureReason = isFailed\n      ? output?.RefusalReason || chosenStep.ErrorMessage || 'Transfer could not complete'\n      : null;\n\n    let hopChain: AgentHandoffParticipant[] | null = null;\n    if (Array.isArray(output?.Chain) && output.Chain.length >= 2) {\n      const chainParticipants = output.Chain.map(hopAgentId =>\n        resolveParticipant(hopAgentId, null, agents)\n      );\n      chainParticipants.push(targetParticipant);\n      hopChain = chainParticipants;\n    }\n\n    result.set(detailId, {\n      SourceAgent: sourceParticipant,\n      TargetAgent: targetParticipant,\n      PresetName: presetName,\n      Brief: brief,\n      Reason: reason,\n      Status: status,\n      FailureReason: failureReason,\n      HopChain: hopChain,\n      TargetDetailId: resolvedTargetDetailId,\n    });\n  }\n\n  return result;\n}\n\n/**\n * Resolves `MessageHandedOffFromInfo` for a target message row when its parent row handed off to it.\n */\nexport function ResolveHandedOffFromForMessage(\n  message: MJConversationDetailEntity,\n  handoffsByDetailId: ReadonlyMap<string, MessageHandoffInfo> | null | undefined\n): MessageHandedOffFromInfo | null {\n  if (!handoffsByDetailId || handoffsByDetailId.size === 0 || message.Role !== 'AI') {\n    return null;\n  }\n\n  if (message.ParentID) {\n    const parentHandoff = LookupHandoffByDetailId(handoffsByDetailId, message.ParentID);\n    if (\n      parentHandoff &&\n      parentHandoff.Status !== 'Failed' &&\n      (!parentHandoff.TargetAgent.ID ||\n        !message.AgentID ||\n        UUIDsEqual(parentHandoff.TargetAgent.ID, message.AgentID))\n    ) {\n      return {\n        SourceAgent: parentHandoff.SourceAgent,\n        TargetAgent: parentHandoff.TargetAgent,\n        PresetName: parentHandoff.PresetName ?? null,\n        Brief: parentHandoff.Brief ?? null,\n        Reason: parentHandoff.Reason ?? null,\n        HopChain: parentHandoff.HopChain ?? null,\n        SourceDetailId: message.ParentID,\n      };\n    }\n  }\n\n  for (const [sourceDetailId, handoff] of handoffsByDetailId.entries()) {\n    if (\n      handoff.Status !== 'Failed' &&\n      handoff.TargetDetailId &&\n      UUIDsEqual(handoff.TargetDetailId, message.ID)\n    ) {\n      return {\n        SourceAgent: handoff.SourceAgent,\n        TargetAgent: handoff.TargetAgent,\n        PresetName: handoff.PresetName ?? null,\n        Brief: handoff.Brief ?? null,\n        Reason: handoff.Reason ?? null,\n        HopChain: handoff.HopChain ?? null,\n        SourceDetailId: sourceDetailId,\n      };\n    }\n  }\n\n  return null;\n}\n"]}

package/dist/lib/utils/agent-turn-routing.d.ts

@@ -10,13 +10,22 @@ import type { AgentReplyMode, AgentTurnTarget } from '../models/agent-turn.model
 export interface AgentTurnCandidates {
     /** Agents the message tags, in the order they appear. */
     MentionedAgentIds: readonly string[];
+    /** People the message tags (`@Person`). Addressing a person with no agent tag starts no agent turn. */
+    MentionedUserIds?: readonly string[];
+    /** The agent of the message this one replies to (`ParentID` -> `Role === 'AI'`), when set. */
+    ReplyParentAgentId?: string | null;
+    /** True when this message replies (`ParentID`) to another person's message (`Role === 'User'`). */
+    ReplyParentIsHuman?: boolean;
     /** The last agent that answered in the conversation, other than the conversation manager. */
     ContinuityAgentId: string | null;
     /**
      * True when a routing decision put `ContinuityAgentId` there in place of the last agent that
-     * answered. The turn is then labelled `DecisionRouted` instead of `Continuity`.
+     * answered (or confirmed it in a multi-person chat). The turn is then labelled `DecisionRouted`
+     * instead of `Continuity`.
      */
     ContinuityDecisionRouted?: boolean;
+    /** True when a routing decision in a multi-person chat concluded the message is addressed to a person. */
+    DecisionAddressedToHuman?: boolean;
     /** The agent pinned on the conversation. */
     ConversationDefaultAgentId: string | null;
     /** The host's `DefaultAgentId` input. */
@@ -31,23 +40,32 @@ export interface AgentTurnRules {
     /** The agents that may answer. Null allows every agent. */
     AllowedAgentIDs: readonly string[] | null;
 }
+/**
+ * True when a message with no allowed `@Agent` mention is intentionally addressed to a person
+ * rather than an agent: it tags a person (`@Person`), replies (`ParentID`) to another person's
+ * message, or was judged human-addressed by the routing decision.
+ */
+export declare function IsAddressedToHuman(candidates: AgentTurnCandidates): boolean;
 /**
  * Picks the agent and route for one message, or null when no turn starts.
  *
- * The order is MJ's: the first tagged agent the host allows, then (under `Always` only) the last
- * agent that answered, the conversation's pinned agent, the host's default agent, and the
- * conversation manager. A candidate the host doesn't allow is skipped. A continuity candidate that
- * a routing decision chose (`ContinuityDecisionRouted`) takes the `DecisionRouted` label.
+ * The order is MJ's: the first tagged agent the host allows, a direct thread reply (`ParentID`) to
+ * a runnable agent, a continuity candidate that a routing decision chose (`DecisionRouted`), and
+ * then (under `Always` only) the last agent that answered, the conversation's pinned agent, the
+ * host's default agent, and the conversation manager. A message that tags a person, replies to
+ * another person's message, or receives a `NoAgent` routing decision with no allowed `@Agent` tag
+ * starts no turn. A candidate the host doesn't allow is skipped.
  *
  * A continuity or default candidate that `isKnownAgent` doesn't recognise falls back to the
  * conversation manager, as MJ always has, rather than to the next route. A tagged agent is taken
- * as tagged.
+ * as tagged; a `ThreadReply` target must pass `isRunnableAgent`.
  *
  * @param candidates The agent each route would use.
  * @param rules The host's reply mode and allowed list.
  * @param isKnownAgent True when the agent exists in the client's agent catalog.
+ * @param isRunnableAgent True when the current user can run the agent directly (defaults to `isKnownAgent`).
  */
-export declare function ResolveAgentTurn(candidates: AgentTurnCandidates, rules: AgentTurnRules, isKnownAgent: (agentId: string) => boolean): AgentTurnTarget | null;
+export declare function ResolveAgentTurn(candidates: AgentTurnCandidates, rules: AgentTurnRules, isKnownAgent: (agentId: string) => boolean, isRunnableAgent?: (agentId: string) => boolean): AgentTurnTarget | null;
 /** A task-graph step that runs an agent, as the conversation manager emits it. */
 interface AgentTaskStep {
     kind: string;
@@ -66,5 +84,42 @@ interface AgentTaskStep {
  * @returns The disallowed names, each once, in the order they appear. Empty when all are allowed.
  */
 export declare function FindDisallowedTaskGraphAgents(steps: ReadonlyArray<AgentTaskStep>, allowedAgentIDs: readonly string[] | null, resolveAgentId: (agentName: string) => string | null): string[];
+/** Minimal shape of a conversation detail row inspected when resolving continuity routing. */
+export interface ContinuityHistoryMessage {
+    ID?: string | null;
+    Role?: string | null;
+    AgentID?: string | null;
+    ParentID?: string | null;
+    Message?: string | null;
+}
+/**
+ * Returns true when a user message explicitly `@`-mentions the given agent (by JSON mention token
+ * `@{..."id":"<agentId>"...}`, JSON token `@{..."name":"<agentName>"...}`, or plain `@<agentName>`).
+ */
+export declare function MessageMentionsAgent(messageText: string | null | undefined, agentId: string | null | undefined, agentName?: string | null): boolean;
+/**
+ * Walks conversation history from newest to oldest to find the most recent non-manager `AI` message
+ * that owns continuity for the next turn.
+ *
+ * Stops and returns `null` (returning ownership to the conversation manager) when:
+ * - A `User` message explicitly `@`-mentions the conversation manager and no non-manager `AI`
+ *   message has replied since (e.g. the user said `@Sage …` and Sage answered directly).
+ * - An `AI` message from the conversation manager was handed back from another `AI` message
+ *   (`ParentID` references an `AI` message, or the immediately preceding row is a non-manager `AI`
+ *   message in the same turn).
+ */
+export declare function FindContinuityAgentMessage<T extends ContinuityHistoryMessage>(messages: readonly T[], conversationManagerAgentId: string | null, options?: {
+    conversationManagerName?: string | null;
+    isWithinFloor?: (msg: T) => boolean;
+    userMentionsManager?: (msg: T) => boolean;
+}): T | null;
+/**
+ * Convenience wrapper around {@link FindContinuityAgentMessage} returning only the `AgentID`.
+ */
+export declare function FindContinuityAgentId<T extends ContinuityHistoryMessage>(messages: readonly T[], conversationManagerAgentId: string | null, options?: {
+    conversationManagerName?: string | null;
+    isWithinFloor?: (msg: T) => boolean;
+    userMentionsManager?: (msg: T) => boolean;
+}): string | null;
 export {};
 //# sourceMappingURL=agent-turn-routing.d.ts.map

package/dist/lib/utils/agent-turn-routing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-turn-routing.d.ts","sourceRoot":"","sources":["../../../src/lib/utils/agent-turn-routing.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAkB,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAElG,2FAA2F;AAC3F,MAAM,WAAW,mBAAmB;IAChC,yDAAyD;IACzD,iBAAiB,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,6FAA6F;IAC7F,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC;;;OAGG;IACH,wBAAwB,CAAC,EAAE,OAAO,CAAC;IACnC,4CAA4C;IAC5C,0BAA0B,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1C,yCAAyC;IACzC,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,uCAAuC;IACvC,0BAA0B,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7C;AAED,qCAAqC;AACrC,MAAM,WAAW,cAAc;IAC3B,oCAAoC;IACpC,SAAS,EAAE,cAAc,CAAC;IAC1B,2DAA2D;IAC3D,eAAe,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAAC;CAC7C;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAC5B,UAAU,EAAE,mBAAmB,EAC/B,KAAK,EAAE,cAAc,EACrB,YAAY,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,GAC3C,eAAe,GAAG,IAAI,CAsBxB;AAUD,kFAAkF;AAClF,UAAU,aAAa;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,CAAC;CACnD;AAED;;;;;;;;;GASG;AACH,wBAAgB,6BAA6B,CACzC,KAAK,EAAE,aAAa,CAAC,aAAa,CAAC,EACnC,eAAe,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,EACzC,cAAc,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,GACrD,MAAM,EAAE,CAYV"}
+{"version":3,"file":"agent-turn-routing.d.ts","sourceRoot":"","sources":["../../../src/lib/utils/agent-turn-routing.ts"],"names":[],"mappings":"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"}

package/dist/lib/utils/agent-turn-routing.js

@@ -6,27 +6,57 @@
  * @module @memberjunction/ng-conversations
  */
 import { IsAgentAllowed } from '@memberjunction/ai-core-plus';
+import { NormalizeUUID, UUIDsEqual } from '@memberjunction/global';
+/**
+ * True when a message with no allowed `@Agent` mention is intentionally addressed to a person
+ * rather than an agent: it tags a person (`@Person`), replies (`ParentID`) to another person's
+ * message, or was judged human-addressed by the routing decision.
+ */
+export function IsAddressedToHuman(candidates) {
+    return (candidates.MentionedUserIds?.length ?? 0) > 0
+        || Boolean(candidates.ReplyParentIsHuman)
+        || Boolean(candidates.DecisionAddressedToHuman);
+}
 /**
  * Picks the agent and route for one message, or null when no turn starts.
  *
- * The order is MJ's: the first tagged agent the host allows, then (under `Always` only) the last
- * agent that answered, the conversation's pinned agent, the host's default agent, and the
- * conversation manager. A candidate the host doesn't allow is skipped. A continuity candidate that
- * a routing decision chose (`ContinuityDecisionRouted`) takes the `DecisionRouted` label.
+ * The order is MJ's: the first tagged agent the host allows, a direct thread reply (`ParentID`) to
+ * a runnable agent, a continuity candidate that a routing decision chose (`DecisionRouted`), and
+ * then (under `Always` only) the last agent that answered, the conversation's pinned agent, the
+ * host's default agent, and the conversation manager. A message that tags a person, replies to
+ * another person's message, or receives a `NoAgent` routing decision with no allowed `@Agent` tag
+ * starts no turn. A candidate the host doesn't allow is skipped.
  *
  * A continuity or default candidate that `isKnownAgent` doesn't recognise falls back to the
  * conversation manager, as MJ always has, rather than to the next route. A tagged agent is taken
- * as tagged.
+ * as tagged; a `ThreadReply` target must pass `isRunnableAgent`.
  *
  * @param candidates The agent each route would use.
  * @param rules The host's reply mode and allowed list.
  * @param isKnownAgent True when the agent exists in the client's agent catalog.
+ * @param isRunnableAgent True when the current user can run the agent directly (defaults to `isKnownAgent`).
  */
-export function ResolveAgentTurn(candidates, rules, isKnownAgent) {
+export function ResolveAgentTurn(candidates, rules, isKnownAgent, isRunnableAgent = isKnownAgent) {
     const mentioned = candidates.MentionedAgentIds.find(id => IsAgentAllowed(id, rules.AllowedAgentIDs));
     if (mentioned) {
         return { AgentId: mentioned, Route: 'Mention' };
     }
+    if ((candidates.MentionedUserIds?.length ?? 0) > 0 || candidates.ReplyParentIsHuman) {
+        return null;
+    }
+    const replyAgent = candidates.ReplyParentAgentId;
+    if (replyAgent && IsAgentAllowed(replyAgent, rules.AllowedAgentIDs) && isRunnableAgent(replyAgent)) {
+        return { AgentId: replyAgent, Route: 'ThreadReply' };
+    }
+    if (candidates.DecisionAddressedToHuman) {
+        return null;
+    }
+    if (candidates.ContinuityDecisionRouted
+        && candidates.ContinuityAgentId
+        && IsAgentAllowed(candidates.ContinuityAgentId, rules.AllowedAgentIDs)
+        && isKnownAgent(candidates.ContinuityAgentId)) {
+        return { AgentId: candidates.ContinuityAgentId, Route: 'DecisionRouted' };
+    }
     if (rules.ReplyMode === 'MentionOnly') {
         return null;
     }
@@ -81,4 +111,115 @@ function agentNameOf(configuration) {
     }
     return null;
 }
+/**
+ * Returns true when a user message explicitly `@`-mentions the given agent (by JSON mention token
+ * `@{..."id":"<agentId>"...}`, JSON token `@{..."name":"<agentName>"...}`, or plain `@<agentName>`).
+ */
+export function MessageMentionsAgent(messageText, agentId, agentName) {
+    if (!messageText) {
+        return false;
+    }
+    const normalizedId = NormalizeUUID(agentId ?? '');
+    const normalizedName = (agentName ?? '').trim().toLowerCase();
+    let cursor = 0;
+    while (cursor < messageText.length) {
+        const openIdx = messageText.indexOf('@{', cursor);
+        if (openIdx === -1) {
+            break;
+        }
+        const closeIdx = messageText.indexOf('}', openIdx + 2);
+        if (closeIdx === -1) {
+            break;
+        }
+        const body = messageText.slice(openIdx + 2, closeIdx);
+        cursor = closeIdx + 1;
+        if (!body) {
+            continue;
+        }
+        try {
+            const parsed = JSON.parse(`{${body}}`);
+            if (parsed.type && parsed.type !== 'agent') {
+                continue;
+            }
+            if (normalizedId && typeof parsed.id === 'string' && UUIDsEqual(parsed.id, normalizedId)) {
+                return true;
+            }
+            if (normalizedName && typeof parsed.name === 'string' && parsed.name.trim().toLowerCase() === normalizedName) {
+                return true;
+            }
+        }
+        catch {
+            // Ignore malformed token and continue scanning
+        }
+    }
+    if (normalizedName) {
+        const escaped = normalizedName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        const plainMention = new RegExp(`(?:^|\\s)@${escaped}(?=\\b|\\s|$)`, 'i');
+        if (plainMention.test(messageText)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Walks conversation history from newest to oldest to find the most recent non-manager `AI` message
+ * that owns continuity for the next turn.
+ *
+ * Stops and returns `null` (returning ownership to the conversation manager) when:
+ * - A `User` message explicitly `@`-mentions the conversation manager and no non-manager `AI`
+ *   message has replied since (e.g. the user said `@Sage …` and Sage answered directly).
+ * - An `AI` message from the conversation manager was handed back from another `AI` message
+ *   (`ParentID` references an `AI` message, or the immediately preceding row is a non-manager `AI`
+ *   message in the same turn).
+ */
+export function FindContinuityAgentMessage(messages, conversationManagerAgentId, options) {
+    const normalizedManagerId = NormalizeUUID(conversationManagerAgentId ?? '');
+    const managerName = options?.conversationManagerName ?? 'Sage';
+    const byId = new Map();
+    for (const m of messages) {
+        if (m.ID) {
+            byId.set(NormalizeUUID(m.ID), m);
+        }
+    }
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const msg = messages[i];
+        if (options?.isWithinFloor && !options.isWithinFloor(msg)) {
+            continue;
+        }
+        if (msg.Role === 'AI' && msg.AgentID) {
+            const isManager = normalizedManagerId.length > 0 && UUIDsEqual(msg.AgentID, normalizedManagerId);
+            if (!isManager) {
+                return msg;
+            }
+            // Conversation manager AI row: check if it is a handback from another AI row
+            const parent = msg.ParentID ? byId.get(NormalizeUUID(msg.ParentID)) : undefined;
+            if (parent && parent.Role === 'AI') {
+                return null;
+            }
+            const prev = i > 0 ? messages[i - 1] : undefined;
+            if (prev &&
+                prev.Role === 'AI' &&
+                prev.AgentID &&
+                !UUIDsEqual(prev.AgentID, normalizedManagerId)) {
+                return null;
+            }
+            continue;
+        }
+        if (msg.Role === 'User') {
+            const mentionsManager = options?.userMentionsManager
+                ? options.userMentionsManager(msg)
+                : MessageMentionsAgent(msg.Message, conversationManagerAgentId, managerName);
+            if (mentionsManager) {
+                return null;
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Convenience wrapper around {@link FindContinuityAgentMessage} returning only the `AgentID`.
+ */
+export function FindContinuityAgentId(messages, conversationManagerAgentId, options) {
+    return FindContinuityAgentMessage(messages, conversationManagerAgentId, options)?.AgentID ?? null;
+}
 //# sourceMappingURL=agent-turn-routing.js.map