@memberjunction/server 5.38.0 → 5.39.0

package/src/resolvers/IntegrationProgressResolver.ts

@@ -0,0 +1,220 @@
+/**
+ * IntegrationProgressResolver — GraphQL subscription surface for long-running
+ * integration events (plan.md §11).
+ *
+ * Exposes a SINGLE @Subscription topic carrying structured progress notifications
+ * for every kind of integration run — metadata refresh, connector creation, sync,
+ * and RSU — so a UI can stream live updates instead of polling
+ * IntegrationTailRunEvents. Filtering by `runID`, `companyIntegrationID`, and `kind`
+ * happens in the subscription filter, exactly like PipelineProgressResolver.
+ *
+ * Wiring through the MJ event system: server-side producers (the
+ * IntegrationProgressEmitter, the connector-creation pipeline, the sync engine,
+ * the RSU pipeline) call the exported {@link PublishIntegrationProgress} helper,
+ * which forwards onto the same `PubSubManager` PubSub infrastructure that backs
+ * PipelineProgress and cache-invalidation events — NOT a parallel mechanism.
+ */
+import { Resolver, Subscription, Root, ObjectType, Field, Int, Arg } from 'type-graphql';
+import { LogError } from '@memberjunction/core';
+import type {
+    IntegrationRunKind,
+    IntegrationProgressEventType,
+    IntegrationProgressLevel,
+} from '@memberjunction/integration-progress-artifacts';
+import { PubSubManager } from '../generic/PubSubManager.js';
+
+/**
+ * The single PubSub topic all integration progress notifications ride. Mirrors
+ * PIPELINE_PROGRESS_TOPIC — one topic, filtered per-subscriber by run/connector/kind.
+ */
+export const INTEGRATION_PROGRESS_TOPIC = 'INTEGRATION_PROGRESS';
+
+/**
+ * Logical channels (the "topic enum" of plan.md §11) a subscriber can scope to.
+ * These map 1:1 onto a subset of {@link IntegrationRunKind} so a UI can subscribe
+ * to, e.g., only sync progress without parsing every notification. Expressed as a
+ * string union (per the union-types-over-enums convention) and surfaced over
+ * GraphQL as a plain String argument/field.
+ */
+export type IntegrationProgressTopic =
+    | 'MetadataRefresh'
+    | 'ConnectorCreation'
+    | 'Sync'
+    | 'RSU';
+
+/**
+ * Maps an {@link IntegrationRunKind} (the vocabulary the emitter writes) onto the
+ * coarser {@link IntegrationProgressTopic} channel a subscriber filters by. Kinds
+ * without a dedicated channel resolve to `undefined` and only match unscoped
+ * subscriptions.
+ */
+const RUN_KIND_TO_TOPIC: Readonly<Record<IntegrationRunKind, IntegrationProgressTopic | undefined>> = {
+    Discovery: 'MetadataRefresh',
+    Enrichment: 'MetadataRefresh',
+    ConnectorCreation: 'ConnectorCreation',
+    SyncRun: 'Sync',
+    RSU: 'RSU',
+    TableCreation: 'RSU',
+    Other: undefined,
+};
+
+/** Resolve the logical channel for a run kind (helper kept tiny + testable). */
+export function IntegrationProgressTopicForKind(kind: IntegrationRunKind): IntegrationProgressTopic | undefined {
+    return RUN_KIND_TO_TOPIC[kind];
+}
+
+/**
+ * A single integration progress notification pushed to the subscription topic.
+ * Carries the structured shape plan.md §11 asks for — the subsystem-specific
+ * `data` payload is serialized into `DataJSON` so the GraphQL field stays a scalar.
+ */
+@ObjectType()
+export class IntegrationProgressNotification {
+    /** The run this event belongs to (matches manifest.runID). */
+    @Field(() => String)
+    RunID: string;
+
+    /** The connector (CompanyIntegration) the run is for, when known. */
+    @Field(() => String, { nullable: true })
+    CompanyIntegrationID?: string;
+
+    /** What kind of run produced this event (IntegrationRunKind, as a string). */
+    @Field(() => String)
+    Kind: string;
+
+    /** The logical channel this notification belongs to (IntegrationProgressTopic). */
+    @Field(() => String, { nullable: true })
+    Topic?: string;
+
+    /** The progress event type (IntegrationProgressEventType, as a string). */
+    @Field(() => String)
+    EventType: string;
+
+    /** Monotonic sequence number within the run. */
+    @Field(() => Int)
+    Seq: number;
+
+    /** Free-form human message (optional). */
+    @Field(() => String, { nullable: true })
+    Message?: string;
+
+    /** Stage name within the run (optional). */
+    @Field(() => String, { nullable: true })
+    Stage?: string;
+
+    /** Severity level (info/warn/error/debug). */
+    @Field(() => String, { nullable: true })
+    Level?: string;
+
+    /** Subsystem-specific structured payload, JSON-serialized. */
+    @Field(() => String, { nullable: true })
+    DataJSON?: string;
+}
+
+/**
+ * Arguments the emitter/pipeline pass to {@link PublishIntegrationProgress}. The
+ * helper derives `Topic` and serializes `Data`, so callers pass the raw event shape.
+ */
+export interface PublishIntegrationProgressArgs {
+    RunID: string;
+    Kind: IntegrationRunKind;
+    EventType: IntegrationProgressEventType;
+    Seq: number;
+    CompanyIntegrationID?: string;
+    Message?: string;
+    Stage?: string;
+    Level?: IntegrationProgressLevel;
+    Data?: Record<string, unknown>;
+}
+
+/** Predicate used by the @Subscription filter — exported so it is unit-testable. */
+export function MatchesIntegrationSubscription(
+    payload: IntegrationProgressNotification,
+    args: { runID?: string; companyIntegrationID?: string; topic?: string }
+): boolean {
+    if (args.runID && payload.RunID !== args.runID) return false;
+    if (args.companyIntegrationID && payload.CompanyIntegrationID !== args.companyIntegrationID) return false;
+    if (args.topic && payload.Topic !== args.topic) return false;
+    return true;
+}
+
+/**
+ * Build the notification payload from publish args. Pure + side-effect free so the
+ * shape (including JSON serialization + topic derivation) can be asserted in tests
+ * without touching PubSub.
+ */
+export function BuildIntegrationProgressNotification(
+    args: PublishIntegrationProgressArgs
+): IntegrationProgressNotification {
+    return {
+        RunID: args.RunID,
+        CompanyIntegrationID: args.CompanyIntegrationID,
+        Kind: args.Kind,
+        Topic: IntegrationProgressTopicForKind(args.Kind),
+        EventType: args.EventType,
+        Seq: args.Seq,
+        Message: args.Message,
+        Stage: args.Stage,
+        Level: args.Level,
+        DataJSON: serializeData(args.Data),
+    };
+}
+
+/** JSON-serialize the subsystem payload, swallowing cyclic/serialization failures. */
+function serializeData(data?: Record<string, unknown>): string | undefined {
+    if (data == null) return undefined;
+    try {
+        return JSON.stringify(data);
+    } catch (e) {
+        LogError(`IntegrationProgressResolver: failed to serialize data payload: ${e}`);
+        return undefined;
+    }
+}
+
+/**
+ * Publish an integration progress event onto the subscription topic. This is the
+ * entry point server-side producers (IntegrationProgressEmitter, pipelines, sync
+ * engine, RSU) call to push live updates to subscribed clients. Uses the shared
+ * PubSubManager — the same infrastructure as PipelineProgress and cache events.
+ *
+ * Returns the published notification (handy for tests / logging); returns
+ * undefined and logs if publishing fails (never throws into the producer path).
+ */
+export function PublishIntegrationProgress(
+    args: PublishIntegrationProgressArgs
+): IntegrationProgressNotification | undefined {
+    try {
+        const notification = BuildIntegrationProgressNotification(args);
+        PubSubManager.Instance.Publish(INTEGRATION_PROGRESS_TOPIC, { ...notification });
+        return notification;
+    } catch (e) {
+        LogError(`PublishIntegrationProgress failed: ${e}`);
+        return undefined;
+    }
+}
+
+@Resolver()
+export class IntegrationProgressResolver {
+    /**
+     * Subscribe to integration progress notifications. With no arguments the
+     * subscriber receives every integration event on this server; pass any of
+     * `runID`, `companyIntegrationID`, or `topic` to scope the stream.
+     */
+    @Subscription(() => IntegrationProgressNotification, {
+        topics: INTEGRATION_PROGRESS_TOPIC,
+        filter: ({ payload, args }: {
+            payload: IntegrationProgressNotification;
+            args: { runID?: string; companyIntegrationID?: string; topic?: string };
+        }) => MatchesIntegrationSubscription(payload, args),
+    })
+    IntegrationProgress(
+        @Root() notification: IntegrationProgressNotification,
+        @Arg('runID', () => String, { nullable: true }) _runID?: string,
+        @Arg('companyIntegrationID', () => String, { nullable: true }) _companyIntegrationID?: string,
+        @Arg('topic', () => String, { nullable: true }) _topic?: string
+    ): IntegrationProgressNotification {
+        return notification;
+    }
+}
+
+export default IntegrationProgressResolver;

package/src/resolvers/MCPResolver.ts

@@ -7,7 +7,7 @@
 
 import { Resolver, Mutation, Query, Subscription, Arg, Ctx, Root, Field, Int, ObjectType, InputType, PubSub, registerEnumType } from 'type-graphql';
 import { PubSubEngine } from 'type-graphql';
-import { LogError, LogStatus, UserInfo, Metadata, RunView } from '@memberjunction/core';
+import { LogError, LogStatus, LogStatusEx, UserInfo, Metadata, RunView } from '@memberjunction/core';
 import {
     MCPClientManager,
     MCPSyncToolsResult,
@@ -705,25 +705,25 @@ export class MCPResolver extends ResolverBase {
 
         try {
             // Check API key scope authorization
-            LogStatus(`MCPResolver: [${ToolName}] Step 1 - Checking API key authorization...`);
+            LogStatusEx({ message: `MCPResolver: [${ToolName}] Step 1 - Checking API key authorization...`, verboseOnly: true });
             await this.CheckAPIKeyScopeAuthorization('mcp:execute', ConnectionID, ctx.userPayload);
-            LogStatus(`MCPResolver: [${ToolName}] Step 1 complete - Authorization passed (${Date.now() - startTime}ms)`);
+            LogStatusEx({ message: `MCPResolver: [${ToolName}] Step 1 complete - Authorization passed (${Date.now() - startTime}ms)`, verboseOnly: true });
 
             // Get the MCP client manager instance and ensure it's initialized
-            LogStatus(`MCPResolver: [${ToolName}] Step 2 - Initializing MCP client manager...`);
+            LogStatusEx({ message: `MCPResolver: [${ToolName}] Step 2 - Initializing MCP client manager...`, verboseOnly: true });
             const manager = MCPClientManager.Instance;
             const publicUrl = this.getPublicUrl();
             await manager.initialize(user, { publicUrl });
-            LogStatus(`MCPResolver: [${ToolName}] Step 2 complete - Manager initialized (${Date.now() - startTime}ms)`);
+            LogStatusEx({ message: `MCPResolver: [${ToolName}] Step 2 complete - Manager initialized (${Date.now() - startTime}ms)`, verboseOnly: true });
 
             // Connect if not already connected
             const isConnected = manager.isConnected(ConnectionID);
-            LogStatus(`MCPResolver: [${ToolName}] Step 3 - Connection status: ${isConnected ? 'already connected' : 'needs connection'}`);
+            LogStatusEx({ message: `MCPResolver: [${ToolName}] Step 3 - Connection status: ${isConnected ? 'already connected' : 'needs connection'}`, verboseOnly: true });
             if (!isConnected) {
                 LogStatus(`MCPResolver: [${ToolName}] Connecting to MCP server for connection ${ConnectionID}...`);
                 try {
                     await manager.connect(ConnectionID, { contextUser: user });
-                    LogStatus(`MCPResolver: [${ToolName}] Step 3 complete - Connected (${Date.now() - startTime}ms)`);
+                    LogStatusEx({ message: `MCPResolver: [${ToolName}] Step 3 complete - Connected (${Date.now() - startTime}ms)`, verboseOnly: true });
                 } catch (connectError) {
                     // Check for OAuth authorization required
                     if (connectError instanceof OAuthAuthorizationRequiredError) {
@@ -763,12 +763,16 @@ export class MCPResolver extends ResolverBase {
             }
 
             // Parse input arguments
-            LogStatus(`MCPResolver: [${ToolName}] Step 4 - Parsing input arguments...`);
+            LogStatusEx({ message: `MCPResolver: [${ToolName}] Step 4 - Parsing input arguments...`, verboseOnly: true });
             let parsedArgs: Record<string, unknown> = {};
             if (InputArgs) {
                 try {
                     parsedArgs = JSON.parse(InputArgs);
-                    LogStatus(`MCPResolver: [${ToolName}] Parsed args: ${JSON.stringify(parsedArgs).substring(0, 200)}...`);
+                    if (configInfo.loggingSettings.graphql.logVariables) {
+                        LogStatus(`MCPResolver: [${ToolName}] Parsed args: ${JSON.stringify(parsedArgs)}`);
+                    } else {
+                        LogStatus(`MCPResolver: [${ToolName}] tool invoked`);
+                    }
                 } catch (parseError) {
                     LogError(`MCPResolver: [${ToolName}] Failed to parse InputArgs: ${parseError}`);
                     return {
@@ -777,18 +781,18 @@ export class MCPResolver extends ResolverBase {
                     };
                 }
             }
-            LogStatus(`MCPResolver: [${ToolName}] Step 4 complete - Args parsed (${Date.now() - startTime}ms)`);
+            LogStatusEx({ message: `MCPResolver: [${ToolName}] Step 4 complete - Args parsed (${Date.now() - startTime}ms)`, verboseOnly: true });
 
             // Call the tool
-            LogStatus(`MCPResolver: [${ToolName}] Step 5 - Calling tool on connection ${ConnectionID}...`);
-            LogStatus(`MCPResolver: [${ToolName}] Tool ID: ${ToolID}`);
+            LogStatusEx({ message: `MCPResolver: [${ToolName}] Step 5 - Calling tool on connection ${ConnectionID}...`, verboseOnly: true });
+            LogStatusEx({ message: `MCPResolver: [${ToolName}] Tool ID: ${ToolID}`, verboseOnly: true });
             const result: MCPToolCallResult = await manager.callTool(
                 ConnectionID,
                 ToolName,
                 { arguments: parsedArgs },
                 { contextUser: user }
             );
-            LogStatus(`MCPResolver: [${ToolName}] Step 5 complete - Tool call returned (${Date.now() - startTime}ms)`);
+            LogStatusEx({ message: `MCPResolver: [${ToolName}] Step 5 complete - Tool call returned (${Date.now() - startTime}ms)`, verboseOnly: true });
 
             // Format the result for the response - wrap in object for GraphQLJSONObject
             let formattedResult: Record<string, unknown> | null = null;
@@ -827,7 +831,7 @@ export class MCPResolver extends ResolverBase {
                 formattedResult = result.structuredContent as Record<string, unknown>;
             }
 
-            LogStatus(`MCPResolver: [${ToolName}] Step 6 complete - Result formatted (${Date.now() - startTime}ms)`);
+            LogStatusEx({ message: `MCPResolver: [${ToolName}] Step 6 complete - Result formatted (${Date.now() - startTime}ms)`, verboseOnly: true });
             LogStatus(`MCPResolver: [${ToolName}] Tool execution complete - Success: ${result.success}, Duration: ${result.durationMs}ms, Total time: ${Date.now() - startTime}ms`);
 
             return {

package/src/resolvers/RunAIAgentResolver.ts

@@ -9,6 +9,7 @@ import { AIEngine } from '@memberjunction/aiengine';
 import { ChatMessage, ChatMessageContent } from '@memberjunction/ai';
 import { ResolverBase } from '../generic/ResolverBase.js';
 import { PUSH_STATUS_UPDATES_TOPIC } from '../generic/PushStatusResolver.js';
+import { startLivenessPulse } from '../generic/FireAndForgetHeartbeat.js';
 import { RequireSystemUser } from '../directives/RequireSystemUser.js';
 import { GetReadWriteProvider } from '../util.js';
 import { SafeJSONParse, UUIDsEqual } from '@memberjunction/global';
@@ -242,6 +243,13 @@ export class RunAIAgentResolver extends ResolverBase {
      */
     private createProgressCallback(pubSub: PubSubEngine, sessionId: string, userPayload: UserPayload, agentRunRef: { current: any }) {
         return (progress: any) => {
+            // Capture the agent run into the ref as soon as any progress event carries it (even
+            // "noise" steps), so the fire-and-forget liveness pulse can read its id/status mid-run
+            // rather than only after RunAgentInConversation returns.
+            if (progress.metadata?.agentRun) {
+                agentRunRef.current = progress.metadata.agentRun;
+            }
+
             // Only publish progress for significant steps (not initialization noise)
             const significantSteps = ['prompt_execution', 'action_execution', 'subagent_execution', 'decision_processing'];
             if (!significantSteps.includes(progress.step)) {
@@ -373,7 +381,10 @@ export class RunAIAgentResolver extends ResolverBase {
         sourceArtifactId?: string,
         sourceArtifactVersionId?: string,
         /** LATENCY OPT #2: Pre-resolved conversationId avoids redundant DB load in AgentRunner */
-        conversationId?: string
+        conversationId?: string,
+        /** Optional external ref the caller can read to observe the agent run as it becomes available
+         *  (used by the fire-and-forget liveness pulse to enrich heartbeats with the run id/status). */
+        runRef?: { current: MJAIAgentRunEntityExtended | null }
     ): Promise<AIAgentRunResult> {
         const startTime = Date.now();
         
@@ -407,8 +418,9 @@ export class RunAIAgentResolver extends ResolverBase {
             // singleton's transaction state with concurrent requests (e.g. conversation deletes).
             const agentRunner = new AgentRunner(p);
 
-            // Track agent run for streaming (use ref to update later)
-            const agentRunRef = { current: null as any };
+            // Track agent run for streaming (use ref to update later). Reuse the caller-supplied
+            // ref when provided so the fire-and-forget liveness pulse can observe the run.
+            const agentRunRef = runRef ?? { current: null as any };
 
             console.log(`🚀 Starting agent execution with sessionId: ${sessionId}`);
 
@@ -1225,12 +1237,23 @@ export class RunAIAgentResolver extends ResolverBase {
         /** LATENCY OPT #2: Pre-resolved conversationId avoids redundant DB load in AgentRunner */
         conversationId?: string
     ): void {
+        // Ref the liveness pulse reads to enrich heartbeats once the run is created.
+        const runRef: { current: MJAIAgentRunEntityExtended | null } = { current: null };
+        const pulse = startLivenessPulse({
+            pubSub,
+            sessionId,
+            resolver: 'RunAIAgentResolver',
+            readStatus: () => runRef.current
+                ? { runId: runRef.current.ID, status: runRef.current.Status }
+                : undefined,
+        });
+
         // Execute in background - errors are handled within, not propagated
         this.executeAIAgent(
             p, dataSource, agentId, userPayload, messagesJson, sessionId, pubSub,
             data, payload, undefined, lastRunId, autoPopulateLastRunPayload,
             configurationId, conversationDetailId, createArtifacts, createNotification,
-            sourceArtifactId, sourceArtifactVersionId, conversationId
+            sourceArtifactId, sourceArtifactVersionId, conversationId, runRef
         ).catch((error: unknown) => {
             // Background execution failed unexpectedly (executeAIAgent has its own try-catch,
             // so this would only fire for truly unexpected errors).
@@ -1249,7 +1272,7 @@ export class RunAIAgentResolver extends ResolverBase {
                 result: JSON.stringify({ success: false, errorMessage })
             };
             this.PublishStreamingUpdate(pubSub, errorCompletionData, userPayload);
-        });
+        }).finally(() => pulse.stop());
     }
 
     /**

package/src/resolvers/RunTestResolver.ts

@@ -16,6 +16,7 @@ import { LogError, LogStatus, UserInfo } from '@memberjunction/core';
 import { TestEngine } from '@memberjunction/testing-engine';
 import { ResolverBase } from '../generic/ResolverBase.js';
 import { PUSH_STATUS_UPDATES_TOPIC } from '../generic/PushStatusResolver.js';
+import { startLivenessPulse } from '../generic/FireAndForgetHeartbeat.js';
 import { TestRunVariables, TestLogMessage, TestRunResult as EngineTestRunResult } from '@memberjunction/testing-engine-base';
 
 // ===== GraphQL Types =====
@@ -254,12 +255,17 @@ export class RunTestResolver extends ResolverBase {
         userPayload: UserPayload,
         user: UserInfo
     ): void {
+        // Keep-alive pulse so a long-running test never trips the client idle timeout.
+        // The client captures the testRunId from progress events for reconciliation.
+        const pulse = startLivenessPulse({ pubSub, sessionId: userPayload.sessionId, resolver: 'RunTestResolver' });
+
         this.executeTest(testId, verbose, environment, tags, variables, pubSub, userPayload, user)
             .catch((error: unknown) => {
                 const errorMessage = (error instanceof Error) ? error.message : 'Unknown background test execution error';
                 LogError(`🔥 Fire-and-forget test execution failed: ${errorMessage}`, undefined, error);
                 this.publishFireAndForgetError(pubSub, userPayload, testId, errorMessage);
-            });
+            })
+            .finally(() => pulse.stop());
     }
 
     /**
@@ -343,6 +349,12 @@ export class RunTestResolver extends ResolverBase {
         userPayload: UserPayload,
         user: UserInfo
     ): void {
+        // Keep-alive pulse so a long-running suite never trips the client idle timeout.
+        // (Suite reconciliation isn't wired: suite progress carries the per-test run id, not the
+        // Test Suite Run id, so the client has no handle to reconcile against — the pulse is the
+        // protection here.)
+        const pulse = startLivenessPulse({ pubSub, sessionId: userPayload.sessionId, resolver: 'RunTestResolver' });
+
         this.executeSuite(
             suiteId, verbose, environment, parallel, tags, variables,
             selectedTestIds, sequenceStart, sequenceEnd, pubSub, userPayload, user
@@ -350,7 +362,7 @@ export class RunTestResolver extends ResolverBase {
             const errorMessage = (error instanceof Error) ? error.message : 'Unknown background suite execution error';
             LogError(`🔥 Fire-and-forget suite execution failed: ${errorMessage}`, undefined, error);
             this.publishFireAndForgetSuiteError(pubSub, userPayload, suiteId, errorMessage);
-        });
+        }).finally(() => pulse.stop());
     }
 
     // ===== Result Building =====

package/src/resolvers/SearchEntitiesResolver.ts

@@ -0,0 +1,173 @@
+import { Arg, Ctx, Field, Float, InputType, Int, ObjectType, Query, Resolver } from 'type-graphql';
+import { EntitySearchResult, SearchEntityParams } from '@memberjunction/core';
+import { AppContext } from '../types.js';
+import { UserCache } from '@memberjunction/sqlserver-dataprovider';
+import { GetReadOnlyProvider } from '../util.js';
+
+/**
+ * GraphQL surface for {@link Metadata.Provider.SearchEntity} / `SearchEntities`.
+ *
+ * Both client forms ({@link GraphQLDataProvider.SearchEntity} and `SearchEntities`)
+ * proxy through this single batched resolver — one HTTP round-trip carries N
+ * per-entity searches in both directions. The actual ranking (lexical +
+ * semantic + RRF blend + permission filter) runs server-side via
+ * `GenericDatabaseProvider.SearchEntity`, fanned out concurrently across
+ * the input list.
+ *
+ * Result groups are aligned by input order so the client can map them back
+ * to the original `params[i]` slot without needing the entity name.
+ */
+
+@InputType()
+export class SearchEntityInput {
+    @Field(() => String)
+    declare EntityName: string;
+
+    @Field(() => String)
+    declare SearchText: string;
+
+    @Field(() => String, { nullable: true })
+    Mode?: 'lexical' | 'semantic' | 'hybrid';
+
+    @Field(() => Int, { nullable: true })
+    RrfK?: number;
+
+    @Field(() => Float, { nullable: true })
+    LexicalWeight?: number;
+
+    @Field(() => Float, { nullable: true })
+    SemanticWeight?: number;
+
+    @Field(() => Int, { nullable: true })
+    TopK?: number;
+
+    @Field(() => Float, { nullable: true })
+    MinScore?: number;
+
+    @Field(() => String, { nullable: true })
+    EntityDocumentID?: string;
+}
+
+@ObjectType()
+export class EntitySearchResultType {
+    @Field(() => String, { nullable: true })
+    declare EntityRecordDocumentID: string | null;
+
+    @Field(() => String)
+    declare RecordID: string;
+
+    @Field(() => Float)
+    declare Score: number;
+
+    @Field(() => String)
+    declare MatchType: 'lexical' | 'semantic' | 'hybrid';
+
+    @Field(() => Float, { nullable: true })
+    LexicalScore?: number | null;
+
+    @Field(() => Float, { nullable: true })
+    SemanticScore?: number | null;
+}
+
+@ObjectType()
+export class EntitySearchResultGroupType {
+    @Field(() => String)
+    declare EntityName: string;
+
+    @Field(() => [EntitySearchResultType])
+    declare Results: EntitySearchResultType[];
+}
+
+@ObjectType()
+export class SearchEntitiesResponseType {
+    @Field(() => Boolean)
+    declare Success: boolean;
+
+    @Field(() => String, { nullable: true })
+    ErrorMessage?: string;
+
+    @Field(() => [EntitySearchResultGroupType])
+    declare Groups: EntitySearchResultGroupType[];
+}
+
+/**
+ * Per-request cap on how many entities a single `SearchEntities` call may
+ * search. Each entity in the batch triggers 2–4 RunViews server-side; an
+ * uncapped batch from a malicious or buggy client could fan out into
+ * thousands of concurrent DB queries. 20 covers every realistic use case
+ * (agent prompt seeding, multi-entity navbar search) with margin to spare.
+ */
+const MAX_SEARCH_ENTITIES_BATCH_SIZE = 20;
+
+@Resolver(SearchEntitiesResponseType)
+export class SearchEntitiesResolver {
+    @Query(() => SearchEntitiesResponseType)
+    async SearchEntities(
+        @Ctx() { providers, userPayload }: AppContext,
+        @Arg('params', () => [SearchEntityInput]) params: SearchEntityInput[]
+    ): Promise<SearchEntitiesResponseType> {
+        try {
+            if (params.length > MAX_SEARCH_ENTITIES_BATCH_SIZE) {
+                return {
+                    Success: false,
+                    ErrorMessage: `Batch size ${params.length} exceeds the per-request cap of ${MAX_SEARCH_ENTITIES_BATCH_SIZE}. Split the request.`,
+                    Groups: params.map(p => ({ EntityName: p.EntityName, Results: [] })),
+                };
+            }
+            const md = GetReadOnlyProvider(providers);
+            const user = UserCache.Instance.Users.find(
+                (u) => u.Email.trim().toLowerCase() === userPayload.email.trim().toLowerCase()
+            );
+            if (!user) {
+                return {
+                    Success: false,
+                    ErrorMessage: `User ${userPayload.email} not found`,
+                    Groups: params.map(p => ({ EntityName: p.EntityName, Results: [] })),
+                };
+            }
+
+            const callParams: SearchEntityParams[] = params.map(p => ({
+                entityName: p.EntityName,
+                searchText: p.SearchText,
+                options: {
+                    mode: p.Mode ?? 'hybrid',
+                    rrfK: p.RrfK ?? undefined,
+                    weights: {
+                        lexical: p.LexicalWeight ?? undefined,
+                        semantic: p.SemanticWeight ?? undefined,
+                    },
+                    topK: p.TopK ?? undefined,
+                    minScore: p.MinScore ?? undefined,
+                    entityDocumentId: p.EntityDocumentID ?? undefined,
+                    contextUser: user,
+                },
+            }));
+
+            // Server-side provider fans the batch out via Promise.all under the
+            // hood — see ProviderBase.SearchEntities. Results arrive aligned by
+            // input order; we just map each group's records to the GraphQL shape.
+            const groupedResults: EntitySearchResult[][] = await md.SearchEntities(callParams);
+
+            return {
+                Success: true,
+                Groups: groupedResults.map((results, i) => ({
+                    EntityName: params[i].EntityName,
+                    Results: results.map(r => ({
+                        EntityRecordDocumentID: r.entityRecordDocumentId,
+                        RecordID: r.recordId,
+                        Score: r.score,
+                        MatchType: r.matchType,
+                        LexicalScore: r.components.lexical ?? null,
+                        SemanticScore: r.components.semantic ?? null,
+                    })),
+                })),
+            };
+        } catch (e) {
+            return {
+                Success: false,
+                ErrorMessage: e instanceof Error ? e.message : String(e),
+                Groups: params.map(p => ({ EntityName: p.EntityName, Results: [] })),
+            };
+        }
+    }
+}

package/src/resolvers/VectorizeEntityResolver.ts

@@ -90,7 +90,13 @@ export class VectorizeEntityResolver extends ResolverBase {
             };
 
             const result = await syncer.VectorizeEntity(params, currentUser);
-            LogStatus(`VectorizeEntity pipeline ${pipelineRunID} complete: success=${result.success}`);
+            if (result.success) {
+                LogStatus(`VectorizeEntity pipeline ${pipelineRunID} complete: success=true`);
+            } else {
+                // The run finished but some/all records failed to render or upsert. Surface it
+                // loudly instead of logging a bare "success=false" that reads like a clean finish.
+                LogError(`VectorizeEntity pipeline ${pipelineRunID} completed with errors (status=${result.status}): ${result.errorMessage}`);
+            }
         } catch (error) {
             const msg = error instanceof Error ? error.message : String(error);
             LogError(`VectorizeEntity pipeline ${pipelineRunID} failed: ${msg}`);
@@ -110,11 +116,18 @@ export class VectorizeEntityResolver extends ResolverBase {
      * Publish a progress update to the PipelineProgress subscription topic.
      */
     private publishProgress(pipelineRunID: string, update: VectorizeProgressUpdate): void {
+        // Carry a short error summary to the client via CurrentItem when the update reports failures,
+        // so the subscription reflects that the run didn't cleanly succeed.
+        const errorSummary = update.Errors && update.Errors.length > 0
+            ? `${update.Errors.length} record(s) failed — e.g. ${update.Errors[0].Message}`
+            : undefined;
+
         const notification: PipelineProgressNotification = {
             PipelineRunID: pipelineRunID,
             Stage: update.Stage,
             TotalItems: update.TotalRecords,
             ProcessedItems: update.ProcessedRecords,
+            CurrentItem: errorSummary,
             ElapsedMs: update.ElapsedMs,
             PercentComplete: update.PercentComplete,
         };