@memberjunction/server 6.2.0-edge.3 → 6.2.0-edge.5

package/src/realtimeWidget/widgetGuestElevation.ts

@@ -93,8 +93,10 @@ export async function resolveWidgetGuestRunContext(
  * A scoped anonymous session (`IsMagicLinkAnonymous` + `MagicLinkScope.ResourceID`) holds only the
  * narrow relay grants its invite's role carries — deliberately NOT the AI run entities, whose rows
  * leak the rendered system prompt. Unlike {@link resolveWidgetGuestRunContext} no widget instance is
- * required: on the realtime path the agent authority is already server-side (the session config's
- * `targetAgentID`, `CanRun`-gated at session start), so there is no client-supplied agent id to pin.
+ * required: the realtime target is the session config's `targetAgentID`, which the owner can edit, so
+ * the relay re-checks `CanRun` on it for the CALLER before this elevation. Direct actions are refused
+ * for these callers before elevation, so only the delegated agent run and the run-entity writes
+ * execute as the system user.
  *
  * PUBLIC WEB-WIDGET guests are deliberately EXCLUDED (returned unchanged): their seeded role writes
  * run rows under the guest principal, which the `Widget Guest: Own Agent Runs` RLS read filter
@@ -126,6 +128,36 @@ export function ResolveScopedAnonymousRunUser(contextUser: UserInfo): UserInfo {
   return systemUser;
 }
 
+/**
+ * The principal a client-direct call's consolidated RECORDING STORE runs as, once the caller has
+ * already passed the session-ownership and consent gates (#5195).
+ *
+ * The store writes `MJ: Files`, the file↔session link and the session's recording stamp — server
+ * plumbing attributed through the session link, never through the caller. A signed-in user whose only
+ * role is the stock UI role cannot create `MJ: Files`, so running the store as the caller lost every
+ * such user's recording (the object landed in storage, the row never did). It therefore runs as the
+ * system user for signed-in owners, and anonymous sessions keep exactly the
+ * {@link ResolveScopedAnonymousRunUser} behaviour (PUBLIC WEB-WIDGET guests stay on the caller for the
+ * same RLS reason documented there).
+ *
+ * Fails CLOSED: with no system user available the caller is returned, i.e. today's behaviour.
+ * Ownership/consent gates must NEVER use this.
+ */
+export function ResolveRecordingStoreUser(contextUser: UserInfo): UserInfo {
+  if (contextUser?.IsMagicLinkAnonymous || contextUser?.WidgetGuestContext?.WidgetID) {
+    return ResolveScopedAnonymousRunUser(contextUser);
+  }
+  const systemUser = UserCache.Instance.GetSystemUser();
+  if (!systemUser) {
+    LogError(
+      `[Realtime] Cannot elevate the recording store for user ${contextUser?.ID}: no system user available; ` +
+        'storing as the caller.',
+    );
+    return contextUser;
+  }
+  return systemUser;
+}
+
 /**
  * Builds an elevated {@link UserPayload} that runs subsequent agent work as `elevatedUser` while
  * preserving the guest's `sessionId` — so progress/streaming PubSub still routes to the guest's

package/src/resolvers/ActionResolver.ts

@@ -1,14 +1,17 @@
 import { Resolver, Mutation, Arg, Ctx } from "type-graphql";
 import { ActionEngineServer } from "@memberjunction/actions";
 import { EntityActionEngineServer } from "@memberjunction/actions";
-import { Metadata, UserInfo, BaseEntity, CompositeKey, KeyValuePair, LogError } from "@memberjunction/core";
-import { ActionParam, ActionResult } from "@memberjunction/actions-base";
+import { Metadata, UserInfo, BaseEntity, CompositeKey, KeyValuePair, LogError, RunView, DatabaseProviderBase } from "@memberjunction/core";
+import { ActionParam, ActionResult, MJActionEntityExtended } from "@memberjunction/actions-base";
+import { UserCache } from "@memberjunction/generic-database-provider";
 import { Field, InputType, ObjectType } from "type-graphql";
 import { KeyValuePairInput } from "../generic/KeyValuePairInput.js";
 import { AppContext, ProviderInfo } from "../types.js";
-import { CopyScalarsAndArrays, UUIDsEqual } from "@memberjunction/global";
+import { CopyScalarsAndArrays, EscapeSQLString, UUIDsEqual } from "@memberjunction/global";
 import { GetReadOnlyProvider, GetReadWriteProvider } from "../util.js";
 import { ResolverBase } from "../generic/ResolverBase.js";
+import { IsScopeLimitedPrincipal } from "../auth/scopeLimitedPrincipal.js";
+import { EvaluateActionRunAuthorization, IsOwner } from "../auth/actionAuthorization.js";
 
 /**
  * Input type for action parameters
@@ -55,8 +58,8 @@ export class RunActionInput {
   Params?: ActionParamInput[];
 
   /**
-   * Whether to skip logging the action execution
-   * Defaults to false
+   * Ignored. A run started through this API always writes an action execution log row; the field
+   * remains so that clients which send it still validate.
    */
   @Field(() => Boolean, { nullable: true })
   SkipActionLog?: boolean;
@@ -174,7 +177,13 @@ export class ActionResultOutput {
 @Resolver()
 export class ActionResolver extends ResolverBase {
   /**
-   * Mutation for running an action
+   * Mutation for running an action.
+   *
+   * Scope-limited sessions are refused. Any other caller must be authorized for the action — see
+   * {@link EvaluateActionRunAuthorization}: an Owner may run any action; anyone else needs a role that
+   * holds an authorization linked to the action through `MJ: Action Authorizations`, or, when the
+   * action has no such link, an action class that authorizes its caller itself. The run is always
+   * logged.
    * @param input The input parameters for running the action
    * @param ctx The GraphQL context containing user authentication information
    * @returns The result of running the action
@@ -185,20 +194,16 @@ export class ActionResolver extends ResolverBase {
     @Ctx() ctx: AppContext
   ): Promise<ActionResultOutput> {
     try {
+      const user = this.getRunActionPrincipal(ctx);
+
       // Check API key scope authorization for action execution
       await this.CheckAPIKeyScopeAuthorization('action:execute', input.ActionID, ctx.userPayload);
 
-      // Get the user from context
-      const user = ctx.userPayload.userRecord;
-      if (!user) {
-        throw new Error("User is not authenticated");
-      }
-
       // Initialize the action engine
       await ActionEngineServer.Instance.Config(false, user);
 
-      // Get the action by ID
       const action = this.findActionById(input.ActionID);
+      await this.assertCanRunAction(action, user, ctx.providers);
 
       // Parse the parameters
       const params = this.parseActionParameters(input.Params);
@@ -206,7 +211,7 @@ export class ActionResolver extends ResolverBase {
       // Run the action — thread the request-scoped provider so provider-bound
       // actions (e.g. the semantic find-* / Search Entity actions, which call
       // params.Provider.SearchEntity) run against the caller's metadata layer.
-      const result = await this.executeAction(action, user, params, ctx.providers, input.SkipActionLog);
+      const result = await this.executeAction(action, user, params, ctx.providers);
 
       // Return the result
       return this.createActionResult(result);
@@ -215,6 +220,66 @@ export class ActionResolver extends ResolverBase {
     }
   }
 
+  /**
+   * The authenticated caller of RunAction. A scope-limited session is refused: its confinement exists
+   * only as row-level-security filters, and an action can reach data and services those filters never
+   * cover.
+   * @throws Error when there is no user or the session is scope-limited
+   */
+  private getRunActionPrincipal(ctx: AppContext): UserInfo {
+    const user = ctx.userPayload?.userRecord;
+    if (!user) {
+      throw new Error("User is not authenticated");
+    }
+    if (IsScopeLimitedPrincipal(user)) {
+      throw new Error("RunAction is not permitted for scope-limited sessions");
+    }
+    return user;
+  }
+
+  /**
+   * Refuses the run unless the caller is authorized for the action — see
+   * {@link EvaluateActionRunAuthorization}. The `MJ: Action Authorizations` rows, the authorization
+   * tree and the role grants all come from the request's provider, or all from the global provider
+   * when the request carries none.
+   * @throws Error when the caller may not run the action
+   */
+  private async assertCanRunAction(action: MJActionEntityExtended, user: UserInfo, providers: Array<ProviderInfo>): Promise<void> {
+    if (IsOwner(user)) {
+      return; // an Owner may run any action, so nothing needs to be read
+    }
+    const provider = GetReadOnlyProvider(providers, { allowFallbackToReadWrite: true });
+    const actionAuthorizationIDs = await this.loadActionAuthorizationIDs(action.ID, provider);
+    const metadata = provider ?? Metadata.Provider; // global-provider-ok: fallback only when the request carries no provider
+    const actionAuthorizesCaller = ActionEngineServer.Instance.ActionAuthorizesCaller(action);
+    const decision = EvaluateActionRunAuthorization(user, actionAuthorizationIDs, metadata, actionAuthorizesCaller);
+    if (!decision.Allowed) {
+      throw new Error(`Not authorized to run action ${action.ID}: ${decision.Reason}`);
+    }
+  }
+
+  /**
+   * The AuthorizationID of each `MJ: Action Authorizations` row for the action. Read as the system
+   * user: this is the server's own authorization decision, so it must not depend on whether the
+   * caller can read that entity.
+   */
+  private async loadActionAuthorizationIDs(actionID: string, provider: DatabaseProviderBase | null): Promise<string[]> {
+    const systemUser = UserCache.Instance.GetSystemUser();
+    if (!systemUser) {
+      throw new Error("System user not found");
+    }
+    const result = await new RunView(provider).RunView<{ AuthorizationID: string }>({
+      EntityName: 'MJ: Action Authorizations',
+      ExtraFilter: `ActionID='${EscapeSQLString(actionID)}'`,
+      Fields: ['AuthorizationID'],
+      ResultType: 'simple'
+    }, systemUser);
+    if (!result.Success) {
+      throw new Error(`Could not read the authorizations for action ${actionID}: ${result.ErrorMessage}`);
+    }
+    return result.Results.map(row => row.AuthorizationID);
+  }
+
   /**
    * Finds an action by its ID
    * @param actionID The ID of the action to find
@@ -222,7 +287,7 @@ export class ActionResolver extends ResolverBase {
    * @throws Error if the action is not found
    * @private
    */
-  private findActionById(actionID: string): any {
+  private findActionById(actionID: string): MJActionEntityExtended {
     const action = ActionEngineServer.Instance.Actions.find(a => UUIDsEqual(a.ID, actionID));
     if (!action) {
       throw new Error(`Action with ID ${actionID} not found`);
@@ -264,20 +329,18 @@ export class ActionResolver extends ResolverBase {
   }
 
   /**
-   * Executes an action
+   * Executes an action. The run is always logged: a client cannot switch off the action execution log.
    * @param action The action to execute
    * @param user The user context
    * @param params The action parameters
-   * @param skipActionLog Whether to skip action logging
    * @returns The action result
    * @private
    */
   private async executeAction(
-    action: any,
+    action: MJActionEntityExtended,
     user: UserInfo,
     params: ActionParam[],
-    providers: Array<ProviderInfo>,
-    skipActionLog?: boolean
+    providers: Array<ProviderInfo>
   ): Promise<ActionResult> {
     // Resolve the request-scoped provider. Prefer read-write (actions may mutate);
     // fall back to read-only, then to the engine's global-Metadata default when no
@@ -287,7 +350,7 @@ export class ActionResolver extends ResolverBase {
       Action: action,
       ContextUser: user,
       Params: params,
-      SkipActionLog: skipActionLog,
+      SkipActionLog: false,
       Filters: [],
       Provider: provider
     });

package/src/resolvers/AdhocQueryResolver.ts

@@ -1,7 +1,8 @@
 import { Arg, Ctx, Query, Resolver, Field, Int, InputType } from 'type-graphql';
 import { LogError } from '@memberjunction/core';
-import type { DatabasePlatform, IMetadataProvider, RunQueryResult, UserInfo } from '@memberjunction/core';
+import type { DatabaseProviderBase, RunQueryResult, UserInfo } from '@memberjunction/core';
 import { RenderPipeline } from '@memberjunction/generic-database-provider';
+import type { AdhocSQLAuthorizer } from '@memberjunction/actions';
 import { AppContext } from '../types.js';
 import { configInfo } from '../config.js';
 import { GetReadOnlyProvider } from '../util.js';
@@ -73,7 +74,7 @@ export class AdhocQueryResolver extends ResolverBase {
             return this.buildErrorResult('No read-only data source available for ad-hoc query execution');
         }
         const contextUser = context.userPayload?.userRecord;
-        const refusal = this.authorizeRenderedSQL(input.SQL, provider.PlatformKey, context, contextUser);
+        const refusal = this.AuthorizeRenderedSQL(input.SQL, provider, contextUser);
         if (refusal) {
             return this.buildErrorResult(refusal, Date.now() - startTime);
         }
@@ -104,12 +105,14 @@ export class AdhocQueryResolver extends ResolverBase {
      * because raw SQL applies neither (see assertFullQueryUsesReadableEntityViews). The provider
      * renders the same input the same way and only wraps it in server-built paging and a count,
      * so the rendered SQL is the full set of reads. Returns the refusal message, or null.
+     *
+     * `provider` is the read-only provider the SQL will run on; it supplies the platform and the
+     * entity metadata. {@link CreateAdhocSQLAuthorizer} exposes this check to the action engine.
      */
-    private authorizeRenderedSQL(sqlText: string, platform: DatabasePlatform, context: AppContext, contextUser: UserInfo | undefined): string | null {
+    public AuthorizeRenderedSQL(sqlText: string, provider: DatabaseProviderBase, contextUser: UserInfo | undefined): string | null {
         try {
-            const rendered = RenderPipeline.Run(sqlText, { Platform: platform, ContextUser: contextUser, RequireReadStatement: true });
-            const mdProvider: IMetadataProvider | undefined = GetReadOnlyProvider(context.providers, { allowFallbackToReadWrite: true }) ?? undefined;
-            this.assertFullQueryUsesReadableEntityViews(rendered.Trace.AfterTemplates, mdProvider, contextUser, 'ad-hoc SQL');
+            const rendered = RenderPipeline.Run(sqlText, { Platform: provider.PlatformKey, ContextUser: contextUser, RequireReadStatement: true });
+            this.assertFullQueryUsesReadableEntityViews(rendered.Trace.AfterTemplates, provider, contextUser, 'ad-hoc SQL');
             return null;
         } catch (err) {
             return err instanceof Error ? err.message : String(err);
@@ -161,3 +164,18 @@ export class AdhocQueryResolver extends ResolverBase {
         };
     }
 }
+
+/**
+ * The ad-hoc SQL checks MJServer registers with the action engine, so that Run Ad-hoc Query applies
+ * the same checks as {@link AdhocQueryResolver.ExecuteAdhocQuery}: the rendered SQL must be one read
+ * statement that reads only entity views the caller may read in full, and the timeout is limited by
+ * the server's request timeout.
+ * @param requestTimeoutMs the server's request timeout in milliseconds; 0 or less means no limit
+ */
+export function CreateAdhocSQLAuthorizer(requestTimeoutMs: number): AdhocSQLAuthorizer {
+    const resolver = new AdhocQueryResolver();
+    return {
+        Authorize: (sql, provider, contextUser) => resolver.AuthorizeRenderedSQL(sql, provider, contextUser),
+        ClampTimeoutSeconds: (requestedSeconds) => ClampAdhocTimeoutSeconds(requestedSeconds, requestTimeoutMs),
+    };
+}

package/src/resolvers/ArtifactFileResolver.ts

@@ -46,7 +46,11 @@ export class ArtifactFileResolver extends ResolverBase {
         return this.buildDownloadUrl(artifactVersion.FileID, user, p);
     }
 
-    /** Load the File + its storage account/provider and generate a signed URL. */
+    /**
+     * Load the File (as the caller) and generate a signed URL — after the storage gate: the caller must be able to read
+     * the account the file's provider resolves to and every `MJ: Files` row that tracks its object
+     * (`FileStorageEngine.ResolveFileObject`), so an artifact cannot sign an object in an account the caller is refused.
+     */
     private async buildDownloadUrl(
         fileId: string,
         user: ReturnType<ResolverBase['GetUserFromPayload']>,
@@ -58,14 +62,11 @@ export class ArtifactFileResolver extends ResolverBase {
             throw new Error(`File record ${fileId} not found`);
         }
 
-        // Find the storage account for this file's provider using cached metadata
-        await FileStorageEngine.Instance.Config(false, user!);
-        const matchingAccounts = FileStorageEngine.Instance.GetAccountsByProviderID(fileEntity.ProviderID);
-        if (matchingAccounts.length === 0) {
+        // Resolve the storage account for this file's provider, gated for the caller (throws on refusal)
+        const resolved = await FileStorageEngine.Instance.ResolveFileObject(fileEntity, user!, 'Read', provider);
+        if (!resolved) {
             throw new Error(`No FileStorageAccount found for ProviderID ${fileEntity.ProviderID}. Cannot generate download URL.`);
         }
-
-        const driver = await FileStorageEngine.Instance.GetDriver(matchingAccounts[0].ID, user!);
-        return driver.CreatePreAuthDownloadUrl(fileEntity.ProviderKey ?? fileEntity.Name);
+        return resolved.Driver.CreatePreAuthDownloadUrl(resolved.ObjectKey);
     }
 }

package/src/resolvers/CacheStatsResolver.ts

@@ -1,5 +1,6 @@
-import { Field, Float, Int, ObjectType, Query, Resolver } from 'type-graphql';
-import { LocalCacheManager, CacheStats, CacheEntryType } from '@memberjunction/core';
+import { Arg, Field, Float, Int, ObjectType, Query, Resolver } from 'type-graphql';
+import { BaseEngine, BaseEngineRegistry, LocalCacheManager, CacheStats, CacheEntryType } from '@memberjunction/core';
+import type { EngineStateCensus } from '@memberjunction/core';
 import { RequireSystemUser } from '../directives/index.js';
 
 // ============================================================================
@@ -66,10 +67,83 @@ class CacheStatsDetailGQL extends CacheStatsGQL {
     EntityBreakdown: CacheEntityBreakdownGQL[];
 }
 
+@ObjectType()
+class EnginePropertyCensusGQL {
+    @Field(() => String)
+    PropertyName: string;
+
+    @Field(() => String, { nullable: true })
+    EntityName?: string;
+
+    @Field(() => String, { nullable: true })
+    DatasetName?: string;
+
+    @Field(() => Int)
+    RowCount: number;
+
+    @Field(() => String, { nullable: true })
+    MaxUpdatedAt: string | null;
+
+    @Field(() => String, { nullable: true })
+    IdentityHash: string | null;
+
+    @Field(() => Boolean)
+    LoadedSuccessfully: boolean;
+
+    @Field(() => Boolean)
+    PermissionDenied: boolean;
+}
+
+@ObjectType()
+class EngineDerivedCountGQL {
+    @Field(() => String)
+    Name: string;
+
+    @Field(() => Int)
+    Value: number;
+}
+
+@ObjectType()
+class EngineStateCensusGQL {
+    @Field(() => String)
+    EngineClass: string;
+
+    @Field(() => Boolean)
+    Loaded: boolean;
+
+    @Field(() => Boolean)
+    PermissionConstrained: boolean;
+
+    @Field(() => [EnginePropertyCensusGQL])
+    Properties: EnginePropertyCensusGQL[];
+
+    @Field(() => [EngineDerivedCountGQL])
+    Derived: EngineDerivedCountGQL[];
+}
+
 // ============================================================================
 // Helpers (pure core)
 // ============================================================================
 
+function censusToGQL(census: EngineStateCensus): EngineStateCensusGQL {
+    const gql = new EngineStateCensusGQL();
+    gql.EngineClass = census.EngineClass;
+    gql.Loaded = census.Loaded;
+    gql.PermissionConstrained = census.PermissionConstrained;
+    gql.Properties = census.Properties.map(p => Object.assign(new EnginePropertyCensusGQL(), p));
+    gql.Derived = Object.entries(census.Derived).map(([Name, Value]) => Object.assign(new EngineDerivedCountGQL(), { Name, Value }));
+    return gql;
+}
+
+/** Census of every registered engine in this process, optionally narrowed to one class name. */
+function buildEngineCensus(engineClass?: string): EngineStateCensusGQL[] {
+    return BaseEngineRegistry.Instance.GetAllEngines()
+        .filter((engine): engine is BaseEngine<unknown> => engine instanceof BaseEngine)
+        .filter(engine => !engineClass || engine.constructor.name === engineClass)
+        .map(engine => censusToGQL(engine.GetStateCensus()))
+        .sort((a, b) => a.EngineClass.localeCompare(b.EngineClass));
+}
+
 function toGQL(stats: CacheStats): CacheStatsGQL {
     const gql = new CacheStatsGQL();
     gql.TotalEntries = stats.totalEntries;
@@ -139,4 +213,17 @@ export class CacheStatsResolver {
         result.EntityBreakdown = buildEntityBreakdown();
         return result;
     }
+
+    /**
+     * What each engine in this server process holds — row counts, newest timestamps, a row-version
+     * hash, and engine-specific derived-state counts. Comparing the hashes across servers shows
+     * whether they converged; a derived count of zero next to a full array shows lost derived state.
+     */
+    @RequireSystemUser()
+    @Query(() => [EngineStateCensusGQL])
+    EngineStateCensus(
+        @Arg('EngineClass', () => String, { nullable: true }) engineClass?: string
+    ): EngineStateCensusGQL[] {
+        return buildEngineCensus(engineClass);
+    }
 }

package/src/resolvers/ClientToolRequestResolver.ts

@@ -14,6 +14,7 @@ import { AppContext } from '../types.js';
 import { LogStatus, LogError } from '@memberjunction/core';
 import { ResolverBase } from '../generic/ResolverBase.js';
 import { ClientToolRequestManager, CLIENT_TOOL_REQUEST_TOPIC, ClientToolRequestNotificationPayload } from '@memberjunction/ai-agents';
+import { ParseClientToolMedia } from '@memberjunction/ai-core-plus';
 
 @ObjectType()
 export class ClientToolRequestNotification {
@@ -71,7 +72,9 @@ export class ClientToolRequestResolver extends ResolverBase {
     /**
      * Client sends the result of executing a client tool back to the server.
      * This resolves the pending Promise in ClientToolRequestManager so the
-     * agent loop can continue.
+     * agent loop can continue. `media` is an optional JSON array of images.
+     * When `media` fails validation or `result` is not valid JSON, the request
+     * resolves as a failed result.
      */
     @Mutation(() => Boolean)
     async RespondToClientToolRequest(
@@ -79,15 +82,25 @@ export class ClientToolRequestResolver extends ResolverBase {
         @Arg('success') success: boolean,
         @Arg('result', { nullable: true }) result: string | undefined,
         @Arg('errorMessage', { nullable: true }) errorMessage: string | undefined,
+        @Arg('media', { nullable: true }) media: string | undefined,
         @Ctx() _context: AppContext = {} as AppContext
     ): Promise<boolean> {
         try {
-            const found = ClientToolRequestManager.Instance.ReceiveResponse({
-                RequestID: requestID,
-                Success: success,
-                Result: result ? JSON.parse(result) : undefined,
-                ErrorMessage: errorMessage
-            });
+            const parsedMedia = ParseClientToolMedia(media);
+            // `=== true` narrows the union; this package compiles without strictNullChecks.
+            const found = ClientToolRequestManager.Instance.ReceiveResponse(parsedMedia.ok === true
+                ? {
+                    RequestID: requestID,
+                    Success: success,
+                    Result: result ? JSON.parse(result) : undefined,
+                    ErrorMessage: errorMessage,
+                    Media: parsedMedia.media.length ? parsedMedia.media : undefined
+                }
+                : {
+                    RequestID: requestID,
+                    Success: false,
+                    ErrorMessage: `Client tool media rejected: ${parsedMedia.error}`
+                });
 
             if (!found) {
                 LogError(`RespondToClientToolRequest: no pending request for ${requestID} (may have timed out)`);
@@ -96,6 +109,11 @@ export class ClientToolRequestResolver extends ResolverBase {
         } catch (error) {
             const msg = error instanceof Error ? error.message : String(error);
             LogError(`RespondToClientToolRequest error: ${msg}`);
+            ClientToolRequestManager.Instance.ReceiveResponse({
+                RequestID: requestID,
+                Success: false,
+                ErrorMessage: `Client tool response rejected: ${msg}`
+            });
             return false;
         }
     }

package/src/resolvers/ConversationRunEventsResolver.ts

@@ -7,7 +7,7 @@ import type { AppContext } from '../types.js';
 import { GetReadOnlyProvider } from '../util.js';
 
 /** The run columns the tail reads. */
-type TailRunRow = Pick<MJAIAgentRunEntity, 'ID' | 'Status' | 'Result'>;
+type TailRunRow = Pick<MJAIAgentRunEntity, 'ID' | 'Status' | 'FinalPayload' | 'Result'>;
 
 /** The step columns an event carries. The large data columns are never read. */
 type TailStepRow = Pick<
@@ -15,7 +15,7 @@ type TailStepRow = Pick<
     'StepNumber' | 'StepType' | 'StepName' | 'Status' | 'Success' | 'ErrorMessage' | 'StartedAt' | 'CompletedAt'
 >;
 
-const RUN_FIELDS: (keyof TailRunRow)[] = ['ID', 'Status', 'Result'];
+const RUN_FIELDS: (keyof TailRunRow)[] = ['ID', 'Status', 'FinalPayload', 'Result'];
 const STEP_FIELDS: (keyof TailStepRow)[] = [
     'StepNumber', 'StepType', 'StepName', 'Status', 'Success', 'ErrorMessage', 'StartedAt', 'CompletedAt',
 ];
@@ -94,10 +94,14 @@ export class ConversationRunEventsOutput {
     /**
      * The run's answer, returned only once the run is terminal.
      *
-     * Sourced from `AIAgentRun.Result`, falling back to the conversation detail's message because
-     * `Result` is agent-dependent and null on many successful runs. Still nullable: a caller must
-     * decide a message is finished from {@link IsInFlight} / {@link DetailStatus}, never from the
-     * presence of this field, or it will wait forever on an agent that writes neither.
+     * Sourced from `AIAgentRun.FinalPayload` (`Result` on older rows), then the conversation detail's
+     * message, because the run payload is agent-dependent and null on many successful runs. Still
+     * nullable: a caller must decide a message is finished from {@link IsInFlight} /
+     * {@link DetailStatus}, never from the presence of this field, or it will wait forever on an
+     * agent that writes neither.
+     *
+     * A run that ended without completing (for example `Cancelled`) returns whatever `FinalPayload`
+     * it had saved, which can be partial, so a caller should check {@link RunStatus} first.
      */
     @Field(() => String, { nullable: true })
     FinalPayload?: string;
@@ -206,11 +210,11 @@ export class ConversationRunEventsResolver {
                 // Only meaningful once terminal; sending it mid-run would hand the client a
                 // partial payload it could mistake for the final answer.
                 //
-                // `AIAgentRun.Result` is agent-dependent — it is null on a large share of
-                // genuinely successful runs — so the conversation detail's own message is the
-                // fallback. That is the text the chat renders, so it is the answer a caller
-                // waiting on this field actually wants.
-                FinalPayload: isInFlight ? undefined : (run.Result ?? detail.Message ?? undefined),
+                // `AIAgentRun.FinalPayload` (`Result` on older rows) is agent-dependent — it is
+                // null on a large share of genuinely successful runs — so the conversation detail's
+                // own message is the fallback. That is the text the chat renders, so it is the
+                // answer a caller waiting on this field actually wants.
+                FinalPayload: isInFlight ? undefined : (run.FinalPayload ?? run.Result ?? detail.Message ?? undefined),
                 DetailStatus: detail.Status ?? undefined,
             };
         } catch (e) {