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

package/src/resolvers/RealtimeSessionEventsResolver.ts

@@ -0,0 +1,133 @@
+/**
+ * @fileoverview GraphQL subscription that delivers **realtime session events** to the session they are
+ * addressed to — `subscription RealtimeSessionEvents(agentSessionId: String!)`.
+ *
+ * The event contract lives in `@memberjunction/ai-core-plus` (`realtime-session-events.ts`); the publisher
+ * apps call is `RealtimeSessionEventService`. This resolver is the delivery edge, and its whole job is
+ * authorization, done twice on purpose:
+ *
+ * 1. **At subscribe time** ({@link AuthorizeRealtimeSessionSubscription}). The session row is loaded and
+ *    {@link AuthorizeSessionAccess} must allow the connection's authenticated principal: the session's
+ *    `UserID` must be the caller's user and — for an anonymous widget guest, who shares one Anonymous
+ *    user with every other guest — the guest's signed per-session scope must match the session's
+ *    conversation. A refusal is an error on THIS subscription only (the socket and its other
+ *    subscriptions are untouched) and is the same "not found" whether the session is missing or simply
+ *    not yours, so ids cannot be probed.
+ * 2. **For every event** ({@link RealtimeSessionEventsFilter}). Each published event carries the owner and
+ *    scope snapshot of its session; the filter re-applies the same decision against the CONNECTION's
+ *    identity. Authorization therefore does not rest on a single check at one moment, and a replicated
+ *    event from another server instance is judged exactly like a local one.
+ *
+ * In neither check does a client-supplied value decide who receives anything: `agentSessionId` only
+ * selects WHICH of the caller's own sessions to listen to; the identity it is checked against comes from
+ * the server-authenticated connection context.
+ *
+ * Events have no replay. A subscriber that was disconnected when an event fired recovers durable state
+ * from `RealtimeSessionVerificationStatus` (and from the session itself).
+ *
+ * @module @memberjunction/server
+ */
+
+import { Resolver, Subscription, Root, Arg, ObjectType, Field } from 'type-graphql';
+import { withFilter } from 'graphql-subscriptions';
+import { PubSubManager } from '../generic/PubSubManager.js';
+import {
+    AuthorizeRealtimeSessionSubscription,
+    RealtimeSessionEventsFilter,
+    type RealtimeSessionEventsArgs,
+    type RealtimeSessionEventsContext,
+    type SubscriptionAuthorizationDeps,
+    DEFAULT_SUBSCRIPTION_AUTHORIZATION_DEPS,
+} from '../realtimeSessions/subscriptionAuthorization.js';
+import { REALTIME_SESSION_EVENTS_TOPIC, type RealtimeSessionEventTopicPayload } from '../realtimeSessions/RealtimeSessionEventService.js';
+
+/** One session event as the client receives it. The routing snapshot is deliberately NOT exposed. */
+@ObjectType()
+export class RealtimeSessionEventNotification {
+    /** Event type, e.g. `identity.verified`. Clients ignore types they do not know. */
+    @Field(() => String)
+    Type: string;
+
+    /** The session the event is addressed to. */
+    @Field(() => String)
+    AgentSessionID: string;
+
+    /** ISO-8601 instant the server emitted the event. */
+    @Field(() => String)
+    OccurredAt: string;
+
+    /** The event payload, JSON-encoded. Parse with `ParseRealtimeSessionEvent` from `@memberjunction/ai-core-plus`. */
+    @Field(() => String)
+    PayloadJson: string;
+}
+
+/**
+ * Builds the event stream for one authorized subscription: the shared topic, narrowed by
+ * {@link RealtimeSessionEventsFilter}.
+ */
+function openEventStream(
+    root: unknown,
+    args: RealtimeSessionEventsArgs,
+    context: RealtimeSessionEventsContext,
+    info: unknown,
+): AsyncIterator<RealtimeSessionEventTopicPayload> {
+    const engine = PubSubManager.Instance.PubSubEngine;
+    if (!engine) {
+        throw new Error('Realtime session events are unavailable: PubSub is not configured.');
+    }
+    const filtered = withFilter(
+        () => engine.asyncIterator<RealtimeSessionEventTopicPayload>(REALTIME_SESSION_EVENTS_TOPIC),
+        (payload: RealtimeSessionEventTopicPayload, filterArgs: RealtimeSessionEventsArgs, filterContext: RealtimeSessionEventsContext) =>
+            RealtimeSessionEventsFilter({ payload, args: filterArgs, context: filterContext }),
+    );
+    return filtered(root, args, context, info);
+}
+
+/**
+ * The `subscribe` function: authorize FIRST (asynchronously), then open the stream. Exported (with an
+ * injectable `deps` argument graphql-js never passes) so the whole path is testable end to end.
+ *
+ * graphql-js awaits the value `subscribe` returns and turns a thrown error into a per-operation error
+ * result, which is exactly what a refusal should be (a failure of this subscription, not the socket).
+ */
+export async function AuthorizeAndSubscribeToRealtimeSessionEvents(
+    root: unknown,
+    args: RealtimeSessionEventsArgs,
+    context: RealtimeSessionEventsContext,
+    info: unknown,
+    deps: SubscriptionAuthorizationDeps = DEFAULT_SUBSCRIPTION_AUTHORIZATION_DEPS,
+): Promise<AsyncIterator<RealtimeSessionEventTopicPayload>> {
+    await AuthorizeRealtimeSessionSubscription(args, context, deps);
+    return openEventStream(root, args, context, info);
+}
+
+@Resolver()
+export class RealtimeSessionEventsResolver {
+    /**
+     * Subscribe to the events addressed to one of YOUR realtime sessions.
+     *
+     * @param agentSessionId - the `MJ: AI Agent Sessions` id to listen to. Must be a session the
+     *   authenticated connection owns (and, for an anonymous widget guest, whose signed scope matches);
+     *   otherwise the subscription is refused.
+     */
+    @Subscription(() => RealtimeSessionEventNotification, {
+        // graphql-subscriptions types `ResolverFn` as returning a bare AsyncIterator, but graphql-js
+        // AWAITS what `subscribe` returns (execute/subscribe.js: `await resolveFn(...)`), and awaiting is
+        // the only way to authorize against the database before opening the stream. The typing gap is in
+        // the library; `@ts-expect-error` (not a cast) so this fails to compile the day the type is fixed.
+        // @ts-expect-error subscribe may return Promise<AsyncIterator>; see comment above
+        subscribe: AuthorizeAndSubscribeToRealtimeSessionEvents,
+    })
+    RealtimeSessionEvents(
+        @Root() payload: RealtimeSessionEventTopicPayload,
+        @Arg('agentSessionId', () => String) _agentSessionId: string,
+    ): RealtimeSessionEventNotification {
+        // OwnerUserID / ScopeKey are server-internal filter keys and are intentionally not returned.
+        return {
+            Type: payload.Type,
+            AgentSessionID: payload.AgentSessionID,
+            OccurredAt: payload.OccurredAt,
+            PayloadJson: payload.PayloadJson,
+        };
+    }
+}

package/src/resolvers/RealtimeSessionVerificationResolver.ts

@@ -0,0 +1,174 @@
+/**
+ * @fileoverview GraphQL operations for **mid-session identity verification** of a realtime session.
+ *
+ * A person talking to an agent (often an anonymous widget guest) proves they control an email address
+ * without leaving the conversation. Three operations, all callable only as the session's OWN principal:
+ *
+ * | Operation | Kind | Purpose |
+ * |---|---|---|
+ * | `RequestRealtimeSessionVerification(agentSessionId, name, email)` | mutation | store a pending verification and email a one-time link + a typed code |
+ * | `SubmitRealtimeSessionVerificationCode(agentSessionId, code)` | mutation | redeem the typed code (the fallback for opening the email on another device) |
+ * | `RealtimeSessionVerificationStatus(agentSessionId)` | query | read the current state — the durable backstop for a missed `identity.verified` event |
+ *
+ * The emailed link is redeemed on a different surface — the public `GET/POST /realtime/verify` routes
+ * (`RealtimeVerifyRouter`) — because the person opening it holds no MJ token.
+ *
+ * The decisions, policy and limits live in `realtimeSessions/verificationWorkflow.ts`; this resolver
+ * only identifies the caller from the server-authenticated payload and maps the result. Note that it
+ * reads `userPayload.userRecord` directly and does **not** use `ResolverBase.GetUserFromPayload`: that
+ * helper falls back to an email lookup in the user cache, which would drop an anonymous guest's
+ * per-session scope — and a scope-less anonymous principal must never be treated as a named owner of
+ * the shared Anonymous user's sessions. No authenticated `userRecord` means no access.
+ *
+ * @module @memberjunction/server
+ */
+
+import { Resolver, Mutation, Query, Arg, Ctx, ObjectType, Field, Int } from 'type-graphql';
+import type { UserInfo } from '@memberjunction/core';
+import type { AppContext } from '../types.js';
+import { GetReadWriteProvider } from '../util.js';
+import { NoLog } from '../logging/NoLog.js';
+import { RealtimeSessionVerificationService } from '../realtimeSessions/RealtimeSessionVerificationService.js';
+import type { PrincipalCaller, VerificationOperationResult } from '../realtimeSessions/verificationWorkflow.js';
+
+/** Result of every verification operation. */
+@ObjectType()
+export class RealtimeSessionVerificationResult {
+    /** True when the operation did what was asked. */
+    @Field(() => Boolean)
+    Success: boolean;
+
+    /** The session's verification state after the operation: `unverified`, `pending` or `verified`. */
+    @Field(() => String)
+    VerificationState: string;
+
+    /**
+     * Machine-readable failure reason when `Success` is false — e.g. `invalid_email`, `consumer_domain`,
+     * `domain_blocked`, `rate_limited`, `send_limit_reached`, `invalid_code`, `attempts_exhausted`,
+     * `code_expired`, `session_not_found`, `session_closed`, `verification_unavailable`.
+     */
+    @Field(() => String, { nullable: true })
+    ErrorCode?: string;
+
+    /** A message safe to show a person. */
+    @Field(() => String, { nullable: true })
+    Message?: string;
+
+    /** ISO instant the pending link/code expires. */
+    @Field(() => String, { nullable: true })
+    ExpiresAt?: string;
+
+    /** Verification emails this session may still trigger. */
+    @Field(() => Int, { nullable: true })
+    SendsRemaining?: number;
+
+    /** Wrong code entries left before the pending verification is voided. */
+    @Field(() => Int, { nullable: true })
+    AttemptsRemaining?: number;
+
+    /** Seconds to wait before retrying, when rate limited. */
+    @Field(() => Int, { nullable: true })
+    RetryAfterSeconds?: number;
+
+    /** The verified address, once verified. */
+    @Field(() => String, { nullable: true })
+    VerifiedEmail?: string;
+
+    /** ISO instant verification completed. */
+    @Field(() => String, { nullable: true })
+    VerifiedAt?: string;
+
+    /** The session's new absolute deadline (ISO) when verification extended it. The server enforces it; this is informational. */
+    @Field(() => String, { nullable: true })
+    MaxSessionDeadlineIso?: string;
+}
+
+/** Maps the workflow result onto the GraphQL type. */
+function toResult(result: VerificationOperationResult): RealtimeSessionVerificationResult {
+    return { ...result };
+}
+
+/** The result for a caller with no usable authenticated identity. */
+function notAuthenticated(): RealtimeSessionVerificationResult {
+    return { Success: false, VerificationState: 'unverified', ErrorCode: 'session_not_found', Message: 'Session not found.' };
+}
+
+@Resolver()
+export class RealtimeSessionVerificationResolver {
+    /**
+     * Ask to verify an email for your realtime session. Applies the session's policy (business-domain
+     * rules, blocked domains, send and rate limits), then emails a one-time link plus a short code.
+     *
+     * @param agentSessionId - your `MJ: AI Agent Sessions` id
+     * @param name - the name to greet in the email (sanitised and length-capped server-side)
+     * @param email - the address to verify
+     */
+    @Mutation(() => RealtimeSessionVerificationResult)
+    async RequestRealtimeSessionVerification(
+        @Arg('agentSessionId', () => String) agentSessionId: string,
+        @Arg('name', () => String) name: string,
+        @Arg('email', () => String) @NoLog email: string,
+        @Ctx() context: AppContext,
+    ): Promise<RealtimeSessionVerificationResult> {
+        const caller = this.callerFrom(context);
+        if (!caller) {
+            return notAuthenticated();
+        }
+        return toResult(
+            await RealtimeSessionVerificationService.Instance.RequestVerification(
+                { AgentSessionID: agentSessionId, Name: name, Email: email },
+                caller,
+            ),
+        );
+    }
+
+    /**
+     * Redeem the typed code from the verification email. Single use; voided after too many wrong entries.
+     *
+     * @param agentSessionId - your `MJ: AI Agent Sessions` id
+     * @param code - the code from the email (spaces and dashes are ignored)
+     */
+    @Mutation(() => RealtimeSessionVerificationResult)
+    async SubmitRealtimeSessionVerificationCode(
+        @Arg('agentSessionId', () => String) agentSessionId: string,
+        @Arg('code', () => String) @NoLog code: string,
+        @Ctx() context: AppContext,
+    ): Promise<RealtimeSessionVerificationResult> {
+        const caller = this.callerFrom(context);
+        if (!caller) {
+            return notAuthenticated();
+        }
+        return toResult(await RealtimeSessionVerificationService.Instance.SubmitCode({ AgentSessionID: agentSessionId, Code: code }, caller));
+    }
+
+    /**
+     * Read the current verification state of your realtime session. Use it after a reconnect: session
+     * events have no replay, so this is how a client that missed `identity.verified` finds out.
+     *
+     * @param agentSessionId - your `MJ: AI Agent Sessions` id
+     */
+    @Query(() => RealtimeSessionVerificationResult)
+    async RealtimeSessionVerificationStatus(
+        @Arg('agentSessionId', () => String) agentSessionId: string,
+        @Ctx() context: AppContext,
+    ): Promise<RealtimeSessionVerificationResult> {
+        const caller = this.callerFrom(context);
+        if (!caller) {
+            return notAuthenticated();
+        }
+        return toResult(await RealtimeSessionVerificationService.Instance.GetStatus({ AgentSessionID: agentSessionId }, caller));
+    }
+
+    /**
+     * Builds the caller from the server-authenticated payload, or null when there is none. Identity comes
+     * from `userPayload.userRecord` ONLY (see the module header).
+     */
+    private callerFrom(context: AppContext): PrincipalCaller | null {
+        const contextUser = context.userPayload?.userRecord as UserInfo | undefined;
+        const provider = GetReadWriteProvider(context.providers);
+        if (!contextUser?.ID || !provider) {
+            return null;
+        }
+        return { Kind: 'principal', ContextUser: contextUser, Provider: provider, ClientIp: context.ClientIp };
+    }
+}

package/src/resolvers/RemoteBrowserActionResolver.ts

@@ -24,6 +24,7 @@ import { MJAIAgentSessionEntity, MJAIAgentEntity } from '@memberjunction/core-en
 import { NormalizeInstanceKey, RemoteBrowserEngine } from '@memberjunction/remote-browser-server';
 import { BeginBrowserGoalStep, FinalizeBrowserGoalStep, ExtractCoAgentRunID } from '../agentSessions/remoteBrowserGoalEngine.js';
 import { RemoteBrowserGoalRegistry } from '../agentSessions/remoteBrowserGoalRegistry.js';
+import { SessionRunIDVerifier } from '../agentSessions/SessionRunIDVerifier.js';
 import { randomUUID } from 'node:crypto';
 import {
   RemoteBrowserAction,
@@ -261,6 +262,9 @@ export class RemoteBrowserActionResolver extends ResolverBase {
    */
   private startedScreencasts = new Map<string, number>();
 
+  /** Checks the co-agent run id read from a session's owner-editable `Config_` before a step is attached to it. */
+  private readonly runIDVerifier = new SessionRunIDVerifier();
+
   /**
    * Surfaces whose live tab-audio stream this resolver has already started, keyed by
    * {@link RemoteBrowserActionResolver.streamKey} for the same reason the screencast map is. Entries
@@ -400,7 +404,13 @@ export class RemoteBrowserActionResolver extends ResolverBase {
     const providerName = await this.resolveProviderName(session, contextUser, provider);
     // Observability: nest this goal's many prompt runs under ONE "Browser goal" step on the realtime
     // co-agent run (when the session has one). Best-effort — a null step just means the goal runs unlinked.
-    const coAgentRunID = ExtractCoAgentRunID(session.Config_);
+    // The owner can edit Config_, so its run id is used only when it is a run of this session.
+    const { CoAgentRunID: coAgentRunID } = await this.runIDVerifier.Verify(
+      session.ID,
+      { CoAgentRunID: ExtractCoAgentRunID(session.Config_) },
+      contextUser,
+      provider,
+    );
     const goalStep = await BeginBrowserGoalStep(provider, contextUser, coAgentRunID, goal);
 
     // ASYNC START: a goal loop can run for minutes; do NOT hold this request open for it (browser

package/src/resolvers/RunAIAgentResolver.ts

@@ -13,6 +13,7 @@ import { StartLivenessPulse } from '../generic/FireAndForgetHeartbeat.js';
 import { RequireSystemUser } from '../directives/RequireSystemUser.js';
 import { GetReadWriteProvider } from '../util.js';
 import { ResolveWidgetGuestRunContext, ElevateUserPayload } from '../realtimeWidget/widgetGuestElevation.js';
+import { IsTrustedAgentRunCaller } from './agent-run-data-guard.js';
 import { SafeJSONParse, UUIDsEqual } from '@memberjunction/global';
 import { GetAttachmentService } from '@memberjunction/aiengine';
 import { NotificationEngine } from '@memberjunction/notifications';
@@ -252,6 +253,14 @@ export class RunAIAgentResolver extends ResolverBase {
             throw new Error(`AI Agent "${agentEntity.Name}" is not active (Status: ${agentEntity.Status})`);
         }
 
+        // Enforce agent run permissions for the calling user
+        if (currentUser && typeof AIEngine.Instance.CanUserRunAgent === 'function') {
+            const canRun = await AIEngine.Instance.CanUserRunAgent(agentEntity.ID, currentUser);
+            if (!canRun) {
+                throw new Error(`User does not have permission to run AI Agent "${agentEntity.Name}" (${agentEntity.ID})`);
+            }
+        }
+
         return agentEntity;
     }
 
@@ -293,7 +302,11 @@ export class RunAIAgentResolver extends ResolverBase {
         taskGraphDebug?: string,
         /** History floor for a conversation run — threaded into ExecuteAgentParams.ConversationHistoryFrom,
          *  so the framework's own conversation reads (retrieval tools, artifacts, compaction) honour it too. */
-        conversationHistoryFrom?: Date
+        conversationHistoryFrom?: Date,
+        /** ExecuteAgentParams.TrustReservedRunData: true only for a caller IsTrustedAgentRunCaller accepts. */
+        trustReservedRunData: boolean = false,
+        /** The conversation branch of the run — threaded into ExecuteAgentParams.ConversationBranchID. */
+        conversationBranchId?: string | null
     ): Promise<AIAgentRunResult> {
         const startTime = Date.now();
         // Best-effort handle for persistInFlightAgentFailure. Populated from a
@@ -362,7 +375,10 @@ export class RunAIAgentResolver extends ResolverBase {
                 requestedSkillIDs: requestedSkillIDs,
                 taskGraphDebug: parseTaskGraphDebug(taskGraphDebug),
                 ConversationHistoryFrom: conversationHistoryFrom,
+                ...(conversationBranchId ? { ConversationBranchID: conversationBranchId } : {}),
                 data: parsedData,
+                // Whether the run may read the reserved data keys (scope, agent-type params); BaseAgent drops them otherwise.
+                TrustReservedRunData: trustReservedRunData,
                 context: {
                     dataSource: dataSource
                 }
@@ -561,6 +577,9 @@ export class RunAIAgentResolver extends ResolverBase {
         await this.CheckAPIKeyScopeAuthorization('agent:execute', agentId, userPayload);
 
         const p = GetReadWriteProvider(providers);
+        // Only the system user or an API key holding the agent:trusted scope may set a run's scope and agent-type
+        // params through data; for anyone else BaseAgent drops those keys (ExecuteAgentParams.TrustReservedRunData).
+        const trustRunData = await IsTrustedAgentRunCaller({ UserPayload: userPayload, IsWidgetGuestRun: false, AgentID: agentId });
 
         if (fireAndForget) {
             // Fire-and-forget mode: start execution in background, return immediately.
@@ -569,7 +588,8 @@ export class RunAIAgentResolver extends ResolverBase {
                 p, dataSource, agentId, userPayload, messagesJson, sessionId, pubSub,
                 data, payload, lastRunId, autoPopulateLastRunPayload, configurationId,
                 conversationDetailId, createArtifacts || false, createNotification || false,
-                sourceArtifactId, sourceArtifactVersionId, undefined /*conversationId*/, planMode, requestedSkillIDs, taskGraphDebug
+                sourceArtifactId, sourceArtifactVersionId, undefined /*conversationId*/, planMode, requestedSkillIDs, taskGraphDebug,
+                undefined /*conversationHistoryFrom*/, trustRunData
             );
 
             LogStatus(`🔥 Fire-and-forget: Agent ${agentId} execution started in background for session ${sessionId}`);
@@ -604,7 +624,9 @@ export class RunAIAgentResolver extends ResolverBase {
             undefined, // runRef
             planMode,
             requestedSkillIDs,
-            taskGraphDebug
+            taskGraphDebug,
+            undefined, // conversationHistoryFrom
+            trustRunData
         );
     }
 
@@ -637,6 +659,9 @@ export class RunAIAgentResolver extends ResolverBase {
         @Arg('requestedSkillIDs', () => [String], { nullable: true }) requestedSkillIDs?: string[]
     ): Promise<AIAgentRunResult> {
         const p = GetReadWriteProvider(providers);
+        // @RequireSystemUser admits only the system user, whom the rule trusts; it is still asked, so every
+        // resolver entry that takes a client's data decides the same way.
+        const trustRunData = await IsTrustedAgentRunCaller({ UserPayload: userPayload, IsWidgetGuestRun: false, AgentID: agentId });
         return this.executeAIAgent(
             p,
             dataSource,
@@ -659,7 +684,10 @@ export class RunAIAgentResolver extends ResolverBase {
             undefined, // conversationId (not pre-resolved on this path)
             undefined, // runRef
             planMode,
-            requestedSkillIDs
+            requestedSkillIDs,
+            undefined, // taskGraphDebug
+            undefined, // conversationHistoryFrom
+            trustRunData
         );
     }
 
@@ -752,6 +780,45 @@ export class RunAIAgentResolver extends ResolverBase {
         }
     }
 
+    /**
+     * The ID of this agent's newest root run in the conversation IF the user stopped it, else
+     * null. The query spans the runs that could be the predecessor (settled, or stopped by the
+     * user) and the newest decides, so a stopped run that a later settled run already followed
+     * is not chained to again. Uses the same filter and recognizer as `BaseAgent.findUserStoppedPredecessorRunId`
+     * (`MJAIAgentRunEntityExtended.BuildStoppedPredecessorFilter` / `IsUserStopped`), which carries the stopped run's
+     * completed results into the new run's context, so the two cannot pick different runs.
+     * Fail-soft: a lookup failure means no chaining, never a failed turn.
+     */
+    private async findUserStoppedPredecessorRunId(
+        conversationId: string,
+        agentId: string,
+        branchId: string | null,
+        contextUser: UserInfo,
+        provider: IMetadataProvider
+    ): Promise<string | null> {
+        try {
+            // The run must have replied on this turn's branch path: a run stopped on a sibling branch is not
+            // this path's history. The trunk needs no branch rows; a branch needs them to walk its ancestry.
+            const branches = branchId ? await ConversationEngine.LoadBranchesFresh(conversationId, contextUser, provider) : [];
+            const rv = RunView.FromMetadataProvider(provider);
+            const newest = await rv.RunView<{ ID: string; Status: string; CancellationReason: string | null }>({
+                EntityName: 'MJ: AI Agent Runs',
+                ExtraFilter: MJAIAgentRunEntityExtended.BuildStoppedPredecessorFilter(conversationId, agentId, branchId, branches),
+                OrderBy: '__mj_CreatedAt DESC',
+                MaxRows: 1,
+                Fields: ['ID', 'Status', 'CancellationReason'],
+                ResultType: 'simple',
+                // The row this looks for was written by the Stop button moments ago; read the database, not a cache.
+                BypassCache: true,
+            }, contextUser);
+            const run = newest.Success ? newest.Results?.[0] : undefined;
+            return run && MJAIAgentRunEntityExtended.IsUserStopped(run.Status, run.CancellationReason) ? run.ID : null;
+        } catch (error) {
+            LogError(`findUserStoppedPredecessorRunId failed; the turn runs unchained: ${error instanceof Error ? error.message : String(error)}`);
+            return null;
+        }
+    }
+
     /**
      * When a continuation run completes (lastRunId was provided), sync the corresponding
      * AIAgentRequest by marking it as responded. This keeps the dashboard accurate when
@@ -916,6 +983,12 @@ export class RunAIAgentResolver extends ResolverBase {
         const widgetElevation = await ResolveWidgetGuestRunContext(userPayload, p);
         const effectiveAgentId = widgetElevation ? widgetElevation.PinnedAgentId : agentId;
         const effectiveUserPayload = widgetElevation ? ElevateUserPayload(userPayload, widgetElevation.ElevatedUser) : userPayload;
+        // Only the system user or an API key holding the agent:trusted scope may set a run's scope and agent-type
+        // params through data (ExecuteAgentParams.TrustReservedRunData). Judged on the caller's own payload: a widget
+        // guest runs under an elevated server principal but is never trusted.
+        const trustRunData = await IsTrustedAgentRunCaller({
+            UserPayload: userPayload, IsWidgetGuestRun: widgetElevation !== null, AgentID: agentId,
+        });
 
         try {
             // Parsed before anything loads: a floor the caller asked for must never be dropped.
@@ -934,6 +1007,24 @@ export class RunAIAgentResolver extends ResolverBase {
                 throw new Error(`Conversation detail ${conversationDetailId} not found`);
             }
             const conversationId = currentDetail.ConversationID;
+            // The branch the placeholder row was created on decides which path the run reads.
+            const branchId: string | null = currentDetail.BranchID ?? null;
+
+            // A turn that follows a run the user STOPPED continues that run rather than starting
+            // over: chain it by LastRunID (the chat client never sends one) and, when the caller
+            // supplied no payload, roll the stopped run's FinalPayload into this run's start.
+            let effectiveLastRunId = lastRunId;
+            let effectiveAutoPopulate = autoPopulateLastRunPayload;
+            if (!effectiveLastRunId) {
+                const stoppedRunId = await this.findUserStoppedPredecessorRunId(conversationId, effectiveAgentId, branchId, currentUser, p);
+                if (stoppedRunId) {
+                    effectiveLastRunId = stoppedRunId;
+                    if (effectiveAutoPopulate === undefined && payload == null) {
+                        effectiveAutoPopulate = true;
+                    }
+                    LogStatus(`↩️ Continuing from user-stopped run ${stoppedRunId} (chained by LastRunID)`);
+                }
+            }
 
             // Load conversation history with attachments from DB
             const messages = await this.loadConversationHistoryWithAttachments(
@@ -944,7 +1035,8 @@ export class RunAIAgentResolver extends ResolverBase {
                 // The UI creates the agent-response placeholder row ('⏳ ...') before invoking
                 // this mutation — exclude it so the model never sees an empty assistant turn.
                 [conversationDetailId],
-                historyFrom
+                historyFrom,
+                branchId
             );
 
             // Convert to JSON string for the existing executeAIAgent method
@@ -955,11 +1047,13 @@ export class RunAIAgentResolver extends ResolverBase {
                 // The client will receive the result via WebSocket PubSub completion event.
                 this.executeAgentInBackground(
                     p, dataSource, effectiveAgentId, effectiveUserPayload, messagesJson, sessionId, pubSub,
-                    data, payload, lastRunId, autoPopulateLastRunPayload, configurationId,
+                    data, payload, effectiveLastRunId, effectiveAutoPopulate, configurationId,
                     conversationDetailId, createArtifacts || false, createNotification || false,
                     sourceArtifactId, sourceArtifactVersionId, conversationId, planMode, requestedSkillIDs,
                     undefined, // taskGraphDebug
-                    historyFrom
+                    historyFrom,
+                    trustRunData,
+                    branchId
                 );
 
                 LogStatus(`🔥 Fire-and-forget: Agent ${effectiveAgentId} execution started in background for session ${sessionId}`);
@@ -982,8 +1076,8 @@ export class RunAIAgentResolver extends ResolverBase {
                 data,
                 payload,
                 undefined, // templateData
-                lastRunId,
-                autoPopulateLastRunPayload,
+                effectiveLastRunId,
+                effectiveAutoPopulate,
                 configurationId,
                 conversationDetailId,
                 createArtifacts || false,
@@ -995,7 +1089,9 @@ export class RunAIAgentResolver extends ResolverBase {
                 planMode,
                 requestedSkillIDs,
                 undefined, // taskGraphDebug
-                historyFrom
+                historyFrom,
+                trustRunData,
+                branchId
             );
         } catch (error) {
             const errorMessage = (error as Error).message || 'Unknown error loading conversation history';
@@ -1217,7 +1313,11 @@ export class RunAIAgentResolver extends ResolverBase {
         requestedSkillIDs?: string[],
         taskGraphDebug?: string,
         /** History floor — threaded through to ExecuteAgentParams.ConversationHistoryFrom. */
-        conversationHistoryFrom?: Date
+        conversationHistoryFrom?: Date,
+        /** ExecuteAgentParams.TrustReservedRunData — see executeAIAgent. */
+        trustReservedRunData: boolean = false,
+        /** The conversation branch of the run — threaded through to ExecuteAgentParams.ConversationBranchID. */
+        conversationBranchId?: string | null
     ): void {
         // Ref the liveness pulse reads to enrich heartbeats once the run is created.
         const runRef: { current: MJAIAgentRunEntityExtended | null } = { current: null };
@@ -1237,7 +1337,7 @@ export class RunAIAgentResolver extends ResolverBase {
             data, payload, undefined, lastRunId, autoPopulateLastRunPayload,
             configurationId, conversationDetailId, createArtifacts, createNotification,
             sourceArtifactId, sourceArtifactVersionId, conversationId, runRef, planMode, requestedSkillIDs, taskGraphDebug,
-            conversationHistoryFrom
+            conversationHistoryFrom, trustReservedRunData, conversationBranchId
         ).catch((error: unknown) => {
             // Background execution failed unexpectedly (executeAIAgent has its own try-catch,
             // so this would only fire for truly unexpected errors).
@@ -1277,7 +1377,9 @@ export class RunAIAgentResolver extends ResolverBase {
         provider: IMetadataProvider,
         excludeDetailIds?: string[],
         /** History floor: only rows written at or after it are loaded, and no summary is used. */
-        historyFrom?: Date
+        historyFrom?: Date,
+        /** The branch whose path to load; null reads the trunk. */
+        branchId?: string | null
     ): Promise<ChatMessage[]> {
         // Context windowing (summary boundary + raw tail, or legacy last-N when no
         // summary exists) shares ONE fold implementation with all other callers —
@@ -1294,7 +1396,7 @@ export class RunAIAgentResolver extends ResolverBase {
         //      the agent against zero history.
         //   4. A history floor (`historyFrom`) is applied in the query, so rows before it never
         //      leave the database, and again in the assembly, which then skips the summary.
-        const rows = await ConversationEngine.LoadWindowRowsFresh(conversationId, contextUser, provider, historyFrom);
+        const rows = await ConversationEngine.LoadWindowRowsFresh(conversationId, contextUser, provider, historyFrom, branchId);
         const window = ConversationEngine.AssembleContextWindow(rows, {
             maxTailMessages: maxMessages,
             excludeDetailIds,

package/src/resolvers/RunTemplateResolver.ts

@@ -2,7 +2,7 @@ import { Resolver, Mutation, Arg, Ctx, ObjectType, Field } from 'type-graphql';
 import { AppContext, UserPayload } from '../types.js';
 import { LogError, LogStatus, Metadata, RunView } from '@memberjunction/core';
 import { MJTemplateContentEntity, MJTemplateEntityExtended } from '@memberjunction/core-entities';
-import { TemplateEngineServer } from '@memberjunction/templates';
+import { GetTemplateRunRefusal, TemplateEngineServer } from '@memberjunction/templates';
 import { ResolverBase } from '../generic/ResolverBase.js';
 import { GetReadWriteProvider } from '../util.js';
 
@@ -45,6 +45,18 @@ export class RunTemplateResolver extends ResolverBase {
         try {
             LogStatus(`=== RUNNING TEMPLATE FOR ID: ${templateId} ===`);
 
+            // Same rule as the Template.Run remote operation, checked before anything is loaded
+            const currentUser = this.GetUserFromPayload(userPayload);
+            const p = GetReadWriteProvider(providers);
+            const refusal = GetTemplateRunRefusal(currentUser, p);
+            if (refusal) {
+                return {
+                    success: false,
+                    error: refusal,
+                    executionTimeMs: Date.now() - startTime
+                };
+            }
+
             // Parse context data (JSON string)
             let data = {};
             if (contextData) {
@@ -59,17 +71,6 @@ export class RunTemplateResolver extends ResolverBase {
                 }
             }
 
-            // Get current user from payload
-            const currentUser = this.GetUserFromPayload(userPayload);
-            if (!currentUser) {
-                return {
-                    success: false,
-                    error: 'Unable to determine current user',
-                    executionTimeMs: Date.now() - startTime
-                };
-            }
-            
-            const p = GetReadWriteProvider(providers);
             // Load the template entity
             const templateEntity = await p.GetEntityObject<MJTemplateEntityExtended>('MJ: Templates', currentUser);
             await templateEntity.Load(templateId);