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

package/src/resolvers/UserResolver.ts

@@ -8,6 +8,7 @@ import {
   RequireContextUser,
   RequireLoadedUser,
   RequireRoleProvider,
+  SessionUserFields,
   UserIdExtraFilter,
 } from './currentUserRoles.js';
 
@@ -42,22 +43,7 @@ export class UserResolver extends MJUserResolverBase {
 
     if (context.userPayload.userRecord) {
       const userRecord = context.userPayload.userRecord;
-      const userData = {
-        ID: userRecord.ID,
-        Name: userRecord.Name,
-        FirstName: userRecord.FirstName,
-        LastName: userRecord.LastName,
-        Title: userRecord.Title,
-        Email: userRecord.Email,
-        Type: userRecord.Type,
-        IsActive: userRecord.IsActive,
-        LinkedRecordType: userRecord.LinkedRecordType,
-        EmployeeID: userRecord.EmployeeID,
-        LinkedEntityID: userRecord.LinkedEntityID,
-        LinkedEntityRecordID: userRecord.LinkedEntityRecordID,
-        __mj_CreatedAt: userRecord.__mj_CreatedAt,
-        __mj_UpdatedAt: userRecord.__mj_UpdatedAt,
-      };
+      const userData = SessionUserFields(userRecord);
       console.log('CurrentUser (from userRecord)', userData.Email);
       const provider = GetReadOnlyProvider(context.providers, { allowFallbackToReadWrite: true });
       const mapped = await this.MapFieldNamesToCodeNames('MJ: Users', userData, userRecord, provider) as MJUser_;

package/src/resolvers/__tests__/GetDataResolver.validation.test.ts

@@ -0,0 +1,95 @@
+// type-graphql decorators on the resolver class need the reflect-metadata polyfill.
+import 'reflect-metadata';
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import type { MockInstance } from 'vitest';
+import { SQLExpressionValidator } from '@memberjunction/global';
+
+const { executedSQL } = vi.hoisted(() => ({ executedSQL: [] as string[] }));
+
+// GetData's server bootstrap, provider, auth and driver imports are replaced so the resolver runs
+// offline. The fake driver records every text it is asked to run.
+vi.mock('../../index.js', () => ({ GetDbType: () => 'sqlserver' }));
+vi.mock('@memberjunction/generic-database-provider', () => ({
+  QueryCompositionEngine: class {
+    HasCompositionTokens(): boolean {
+      return false;
+    }
+  },
+}));
+vi.mock('../../util.js', () => ({ GetReadOnlyDataSource: () => ({}), GetReadOnlyProvider: () => null }));
+vi.mock('../../auth/index.js', () => ({ GetSystemUser: async () => ({}) }));
+vi.mock('mssql', () => ({
+  default: {
+    Request: class {
+      async query(text: string): Promise<{ recordset: Array<Record<string, unknown>> }> {
+        executedSQL.push(text);
+        return { recordset: [] };
+      }
+    },
+  },
+}));
+
+import { GetDataResolver, GetDataInputType, GetDataOutputType, RegisterAccessToken } from '../GetDataResolver.js';
+import type { AppContext } from '../../types.js';
+
+const CONTEXT = { dataSources: [] } as unknown as AppContext;
+
+let tokenSeq = 0;
+
+/** Calls GetData with a fresh valid token. */
+async function runGetData(queries: string[]): Promise<GetDataOutputType> {
+  const token = `getdata-validation-${Date.now()}-${++tokenSeq}`;
+  RegisterAccessToken(token, 60_000);
+  const input = Object.assign(new GetDataInputType(), { Token: token, Queries: queries });
+  return new GetDataResolver().GetData(input, CONTEXT);
+}
+
+/** The text of every call to the validator's `validate` method. */
+function validatedTexts(spy: MockInstance<SQLExpressionValidator['validate']>): string[] {
+  return spy.mock.calls.map(([text]) => text);
+}
+
+describe('GetData runs exactly the SQL it validated', () => {
+  beforeEach(() => {
+    executedSQL.length = 0;
+  });
+
+  it('validates and runs the same text when the query contains backslash sequences', async () => {
+    const query = String.raw`SELECT Name FROM __mj.vwFiles WHERE Path = 'C:\new\temp'`;
+    const validateSpy = vi.spyOn(SQLExpressionValidator.Instance, 'validate');
+
+    const output = await runGetData([query]);
+
+    expect(output.ErrorMessages).toEqual([null]);
+    expect(executedSQL).toEqual(validatedTexts(validateSpy));
+    expect(executedSQL).toEqual([query]);
+    expect(validateSpy).toHaveBeenCalledWith(query, { context: 'full_query', Dialect: 'sqlserver' });
+  });
+
+  it('runs the trimmed text that the validator reads', async () => {
+    const validateSpy = vi.spyOn(SQLExpressionValidator.Instance, 'validate');
+
+    const output = await runGetData(['\n  SELECT 1 AS One  \n']);
+
+    expect(output.ErrorMessages).toEqual([null]);
+    expect(executedSQL).toEqual(['SELECT 1 AS One']);
+    expect(validatedTexts(validateSpy)).toEqual(executedSQL);
+  });
+
+  it('refuses a query whose text, as written, does not open with SELECT or WITH', async () => {
+    const output = await runGetData(["-- note\\n SELECT 1\nPRINT 'hello'"]);
+
+    expect(executedSQL).toEqual([]);
+    expect(output.Success).toBe(false);
+    expect(output.ErrorMessages[0]).toMatch(/must start with SELECT or WITH/);
+  });
+
+  it('does not run a refused query and still runs the others', async () => {
+    const output = await runGetData(['SELECT 1; SELECT 2', 'SELECT 1 AS One']);
+
+    expect(executedSQL).toEqual(['SELECT 1 AS One']);
+    expect(output.ErrorMessages[0]).toMatch(/Semicolons are not allowed/);
+    expect(output.ErrorMessages[1]).toBeNull();
+  });
+});

package/src/resolvers/agent-run-data-guard.ts

@@ -0,0 +1,89 @@
+/**
+ * @fileoverview Decides which callers of the agent-run resolvers may set a run's scope or agent-type parameters
+ * through the free-form `data` argument.
+ *
+ * `BaseAgent` and `AgentRunner` read a few `ExecuteAgentParams.data` keys (`RESERVED_AGENT_RUN_DATA_KEYS` in
+ * `@memberjunction/ai-core-plus`) as fallbacks that change what a run is, not just what its prompt says:
+ *  - `PrimaryScopeEntityName`, `PrimaryScopeRecordID`, `SecondaryScopes` decide the run's scope: which
+ *    notes and examples memory is injected, the pre-execution RAG search context, the scoped prompt parts
+ *    and run settings, the scope columns written on the `MJ: AI Agent Runs` row, and what sub-agents
+ *    inherit. On a widget-guest run an explicit scope also beats the returning-visitor scope.
+ *  - `__agentTypePromptParams` is the highest-precedence agent-type parameter layer. It can turn on the
+ *    Loop type's `enableTaskGraphs` capability, and switch decisions on or off.
+ *
+ * The rule lives with the run, not here: `BaseAgent.Execute` drops those keys from every run's `data` unless the
+ * params set `ExecuteAgentParams.TrustReservedRunData`. The resolvers set that marker for the callers
+ * {@link IsTrustedAgentRunCaller} accepts — the system user, and an `mj_sk_*` API key that holds the
+ * {@link TRUSTED_RUN_DATA_SCOPE} scope — and never for a browser or a widget guest. Any user who may create API
+ * keys can mint one for themselves, so a key alone is not enough: an administrator grants the scope. Explorer never
+ * sends these keys. Everything else in `data` (template data, `conversationId`, `appContext`, `clientTools`, ...)
+ * reaches the run unchanged either way.
+ *
+ * @module @memberjunction/server/resolvers
+ */
+import { LogError } from '@memberjunction/core';
+import { GetAPIKeyEngine } from '@memberjunction/api-keys';
+import { UserCache } from '@memberjunction/generic-database-provider';
+import type { UserPayload } from '../types.js';
+
+/**
+ * The API-key scope (`MJ: API Scopes.FullPath`) that makes an `mj_sk_*` key a trusted integration for reserved run
+ * data. Checked against the agent being run, so a key can be trusted for some agents only. `full_access` does not
+ * imply it: the key must hold this scope itself.
+ */
+export const TRUSTED_RUN_DATA_SCOPE = 'agent:trusted';
+
+/** Who sent a run's `data`, as far as {@link IsTrustedAgentRunCaller} needs to know. */
+export interface ClientAgentRunCaller {
+    /**
+     * The request's authenticated payload, BEFORE any widget-guest elevation. `isSystemUser` is set only by
+     * the system API key (and by widget elevation, which {@link IsWidgetGuestRun} overrides); `apiKeyHash`
+     * only by an `mj_sk_*` user API key.
+     */
+    UserPayload: Pick<UserPayload, 'email' | 'isSystemUser' | 'apiKeyHash'>;
+    /** True when the run executes under the widget-guest elevated principal. Such a run is never trusted. */
+    IsWidgetGuestRun: boolean;
+    /** The agent the caller asked to run: the resource the {@link TRUSTED_RUN_DATA_SCOPE} check is made against. */
+    AgentID: string;
+}
+
+/**
+ * Whether a caller may set the reserved run-data keys — the value the agent-run resolvers pass as
+ * `ExecuteAgentParams.TrustReservedRunData`: the system user, or an API key that holds
+ * {@link TRUSTED_RUN_DATA_SCOPE} for this agent, and never a widget-guest run, whatever principal it was elevated to.
+ * A key without the scope is treated like the browser session of the user it belongs to.
+ *
+ * @param caller - Who sent the run's `data`.
+ * @returns `true` when the run may read the reserved keys from `data`.
+ */
+export async function IsTrustedAgentRunCaller(caller: ClientAgentRunCaller): Promise<boolean> {
+    if (caller.IsWidgetGuestRun) {
+        return false;
+    }
+    if (caller.UserPayload.isSystemUser === true) {
+        return true;
+    }
+    const apiKeyHash = caller.UserPayload.apiKeyHash;
+    return apiKeyHash ? keyHoldsTrustedRunDataScope(apiKeyHash, caller.AgentID) : false;
+}
+
+/**
+ * Whether the key explicitly holds {@link TRUSTED_RUN_DATA_SCOPE} for the agent. A key-level rule must match: an
+ * allow that comes from scope enforcement being switched off, or from `defaultBehaviorNoScopes: 'allow'`, matches
+ * no rule and does not count. Any failure counts as not held.
+ */
+async function keyHoldsTrustedRunDataScope(apiKeyHash: string, agentID: string): Promise<boolean> {
+    try {
+        const systemUser = UserCache.Instance.GetSystemUser();
+        if (!systemUser) {
+            return false;
+        }
+        // A probe, not an access decision (the run goes ahead either way), so it is not written to the usage log.
+        const result = await GetAPIKeyEngine().Authorize(apiKeyHash, 'MJAPI', TRUSTED_RUN_DATA_SCOPE, agentID, systemUser,
+            { endpoint: '/graphql', method: 'POST' }, { skipLogging: true });
+        return result.Allowed && result.MatchedKeyRule != null;
+    } catch (e) {
+        LogError(`IsTrustedAgentRunCaller: the ${TRUSTED_RUN_DATA_SCOPE} check failed; the run is not trusted: ${e}`);
+        return false;
+    }
+}

package/src/resolvers/agentVisionConsentAudit.ts

@@ -0,0 +1,82 @@
+/**
+ * @fileoverview The audit trail for agent-vision consent: one `MJ: Audit Logs` row each time a person allows, or stops
+ * letting, agents see their camera and shared screen in a meeting room, including when LiveKit refuses the change.
+ *
+ * The row is saved by the system user, as MJ's other server-written audit rows are, because the person may not be
+ * allowed to create audit rows themselves; `UserID` and `RecordID` are the person. When the audit log type has not
+ * been seeded, the entry goes to the server log instead, so a choice is never left unrecorded.
+ *
+ * Invoked from `RealtimeBridgeResolver.SetLiveKitAgentVision`.
+ *
+ * @module @memberjunction/server
+ */
+
+import { LogError, type IMetadataProvider, type UserInfo } from '@memberjunction/core';
+import type { MJAuditLogEntity } from '@memberjunction/core-entities';
+import { UserCache } from '@memberjunction/generic-database-provider';
+
+/** The seeded audit log type (see `metadata/audit-log-types/.realtime-session-audit-types.json`). */
+export const REALTIME_AGENT_VISION_CONSENT_AUDIT_TYPE = 'Realtime Agent Vision Consent';
+
+const AUDIT_LOG_ENTITY = 'MJ: Audit Logs';
+const USERS_ENTITY = 'MJ: Users';
+
+/** One consent change to record. */
+export interface AgentVisionConsentEntry {
+  /** The person who chose. */
+  User: UserInfo;
+  /** The room they chose for. */
+  RoomName: string;
+  /** `true` to let agents see their camera and shared screen, `false` to stop. */
+  Allow: boolean;
+  /** Whether LiveKit applied the change. */
+  Applied: boolean;
+  /** Why it was not applied. */
+  ErrorMessage?: string;
+}
+
+/**
+ * Writes the audit row for one consent change. Never throws: a failure to audit is logged, and the person's choice
+ * stands as LiveKit applied it.
+ *
+ * @param entry The change to record.
+ * @param provider The request's provider.
+ */
+export async function WriteAgentVisionConsentAudit(entry: AgentVisionConsentEntry, provider: IMetadataProvider | null): Promise<void> {
+  try {
+    const writer = UserCache.Instance.GetSystemUser();
+    const type = provider?.AuditLogTypes?.find((t) => t.Name?.trim().toLowerCase() === REALTIME_AGENT_VISION_CONSENT_AUDIT_TYPE.toLowerCase());
+    if (!provider || !writer || !type) {
+      LogError(`Agent vision consent not audited (${missingReason(provider, writer)}): user ${entry.User.ID}: ${describeChange(entry)}`);
+      return;
+    }
+    const row = await provider.GetEntityObject<MJAuditLogEntity>(AUDIT_LOG_ENTITY, writer);
+    row.NewRecord();
+    row.UserID = entry.User.ID;
+    row.AuditLogTypeID = type.ID;
+    row.Status = entry.Applied ? 'Success' : 'Failed';
+    row.EntityID = provider.EntityByName(USERS_ENTITY)?.ID ?? null;
+    row.RecordID = entry.User.ID;
+    row.Description = describeChange(entry);
+    row.Details = JSON.stringify({ roomName: entry.RoomName, allow: entry.Allow, error: entry.ErrorMessage ?? null });
+    if (!(await row.Save())) {
+      LogError(`Agent vision consent audit row not saved for user ${entry.User.ID}: ${row.LatestResult?.CompleteMessage ?? 'unknown error'}`);
+    }
+  } catch (error) {
+    LogError(`Agent vision consent audit write threw for user ${entry.User.ID}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+/** Why the audit row can't be written: no provider, no system user, or the audit log type isn't seeded. */
+function missingReason(provider: IMetadataProvider | null, writer: UserInfo | undefined | null): string {
+  if (!provider) {
+    return 'no provider';
+  }
+  return writer ? `audit log type '${REALTIME_AGENT_VISION_CONSENT_AUDIT_TYPE}' is not seeded` : 'no system user';
+}
+
+/** One line saying what the person chose, and whether it was applied. */
+function describeChange(entry: AgentVisionConsentEntry): string {
+  const choice = entry.Allow ? 'Let agents see their camera and shared screen' : 'Stopped letting agents see their camera and shared screen';
+  return `${choice} in room ${entry.RoomName}${entry.Applied ? '' : ' (not applied)'}.`;
+}

package/src/resolvers/avatarInputValidation.ts

@@ -0,0 +1,123 @@
+/**
+ * @fileoverview Trust-boundary validation for the self-service avatar mutation
+ * (`UpdateMyAvatar` in `UserAvatarResolver`).
+ *
+ * The browser checks these values too, but its URL check is `new URL(...)`, which happily accepts
+ * `javascript:` and every `data:` type. The server is the boundary, so everything that reaches
+ * `MJ: Users.UserImageURL` / `UserImageIconClass` through the mutation passes through here first.
+ *
+ * Pure: no I/O, no provider, no entity — so it is unit-testable on its own.
+ *
+ * @module @memberjunction/server/resolvers/avatarInputValidation
+ */
+
+/** Largest DECODED image accepted in a `data:` URI. Matches the Explorer upload cap. */
+export const AVATAR_MAX_IMAGE_BYTES = 200 * 1024;
+
+/** Longest `http:` / `https:` image URL accepted. */
+export const AVATAR_MAX_URL_LENGTH = 2048;
+
+/** Longest icon class string accepted. */
+export const AVATAR_MAX_ICON_CLASS_LENGTH = 100;
+
+/**
+ * Longest `data:` value that can still decode to {@link AVATAR_MAX_IMAGE_BYTES}: the longest accepted
+ * prefix plus the padded base64 payload. Anything longer is refused before the pattern scans it.
+ */
+const AVATAR_MAX_DATA_URI_LENGTH = 'data:image/jpeg;base64,'.length + Math.ceil(AVATAR_MAX_IMAGE_BYTES / 3) * 4;
+
+/** `data:image/<raster type>;base64,<payload>` — SVG is deliberately absent (it can carry script). */
+const DATA_URI_PATTERN = /^data:image\/(png|jpeg|jpg|gif|webp);base64,([A-Za-z0-9+/]+={0,2})$/;
+
+/** Lower-case Font Awesome class lists only, e.g. `fa-solid fa-user`. */
+const ICON_CLASS_PATTERN = /^[a-z0-9 -]+$/;
+const FA_TOKEN_PATTERN = /^fa-[a-z0-9-]+$/;
+
+/** The outcome of {@link ValidateAvatarInput}. Empty strings are normalised to `null` (clear). */
+export interface AvatarInputValidationResult {
+    Valid: boolean;
+    /** Why the input was refused. Set only when `Valid` is false. */
+    ErrorMessage?: string;
+    /** The value to store in `UserImageURL`; `null` clears it. */
+    ImageURL: string | null;
+    /** The value to store in `UserImageIconClass`; `null` clears it. */
+    IconClass: string | null;
+}
+
+/**
+ * Validates a requested avatar. Null or empty values clear the corresponding column, so both
+ * null is a valid "revert to default".
+ *
+ * - `imageURL`: a `data:image/(png|jpeg|jpg|gif|webp);base64,...` URI whose decoded size is at most
+ *   {@link AVATAR_MAX_IMAGE_BYTES}, or an absolute `http:`/`https:` URL of at most
+ *   {@link AVATAR_MAX_URL_LENGTH} characters with no whitespace. Everything else is refused.
+ * - `iconClass`: at most {@link AVATAR_MAX_ICON_CLASS_LENGTH} characters of `[a-z0-9 -]`,
+ *   containing at least one `fa-` token.
+ */
+export function ValidateAvatarInput(
+    imageURL: string | null | undefined,
+    iconClass: string | null | undefined
+): AvatarInputValidationResult {
+    const image = imageURL ? imageURL : null;
+    const icon = iconClass ? iconClass : null;
+    const error = (image === null ? undefined : imageUrlError(image)) ?? (icon === null ? undefined : iconClassError(icon));
+    return error ? { Valid: false, ErrorMessage: error, ImageURL: null, IconClass: null } : { Valid: true, ImageURL: image, IconClass: icon };
+}
+
+/** Returns why an image value is refused, or `undefined` when it is acceptable. */
+function imageUrlError(value: string): string | undefined {
+    if (value.startsWith('data:')) {
+        return dataUriError(value);
+    }
+    return httpUrlError(value);
+}
+
+function dataUriError(value: string): string | undefined {
+    if (value.length > AVATAR_MAX_DATA_URI_LENGTH) {
+        return tooLargeError(Math.floor((value.length * 3) / 4));
+    }
+    const match = DATA_URI_PATTERN.exec(value);
+    if (!match || match[2].length % 4 !== 0) {
+        return 'Avatar image must be a base64 PNG, JPEG, GIF or WEBP data URI.';
+    }
+    const decodedBytes = decodedBase64Length(match[2]);
+    return decodedBytes > AVATAR_MAX_IMAGE_BYTES ? tooLargeError(decodedBytes) : undefined;
+}
+
+function tooLargeError(bytes: number): string {
+    return `Avatar image must be ${AVATAR_MAX_IMAGE_BYTES / 1024}KB or smaller (this one is about ${Math.ceil(bytes / 1024)}KB).`;
+}
+
+/** Decoded byte length of a padded base64 string, without decoding it. */
+function decodedBase64Length(base64: string): number {
+    const padding = base64.endsWith('==') ? 2 : base64.endsWith('=') ? 1 : 0;
+    return (base64.length / 4) * 3 - padding;
+}
+
+function httpUrlError(value: string): string | undefined {
+    const refusal = 'Avatar image URL must be an absolute http or https URL.';
+    if (value.length > AVATAR_MAX_URL_LENGTH) {
+        return `Avatar image URL must be ${AVATAR_MAX_URL_LENGTH} characters or fewer.`;
+    }
+    if (/\s/.test(value) || !/^https?:\/\//i.test(value)) {
+        return refusal;
+    }
+    try {
+        const url = new URL(value);
+        return url.protocol === 'http:' || url.protocol === 'https:' ? undefined : refusal;
+    } catch {
+        return refusal;
+    }
+}
+
+/** Returns why an icon class is refused, or `undefined` when it is acceptable. */
+function iconClassError(value: string): string | undefined {
+    const valid =
+        value.length <= AVATAR_MAX_ICON_CLASS_LENGTH &&
+        ICON_CLASS_PATTERN.test(value) &&
+        value.split(' ').some((token) => FA_TOKEN_PATTERN.test(token));
+    return valid
+        ? undefined
+        : `Avatar icon must be a Font Awesome class list (lower-case letters, digits, spaces and hyphens, ` +
+              `${AVATAR_MAX_ICON_CLASS_LENGTH} characters or fewer, including an fa- class).`;
+}

package/src/resolvers/currentUserRoles.ts

@@ -1,4 +1,4 @@
-import { LogError } from '@memberjunction/core';
+import { LogError, UserInfo } from '@memberjunction/core';
 
 /**
  * Guards and filter builders for CurrentUser role loading.
@@ -6,6 +6,37 @@ import { LogError } from '@memberjunction/core';
  * without importing generated GraphQL types or the Apollo config bootstrap.
  */
 
+/**
+ * The session user's own fields, as CurrentUser returns them. The client asks for every field of
+ * `UserInfo` (GraphQLDataProvider builds its query from it), so each one belongs here; anything
+ * left out reaches the client as null (as IsTemplate once did, hiding the template-user banner).
+ */
+export function SessionUserFields(userRecord: UserInfo) {
+  return {
+    ID: userRecord.ID,
+    Name: userRecord.Name,
+    FirstName: userRecord.FirstName,
+    LastName: userRecord.LastName,
+    Title: userRecord.Title,
+    Email: userRecord.Email,
+    Type: userRecord.Type,
+    IsActive: userRecord.IsActive,
+    IsTemplate: userRecord.IsTemplate,
+    LinkedRecordType: userRecord.LinkedRecordType,
+    EmployeeID: userRecord.EmployeeID,
+    LinkedEntityID: userRecord.LinkedEntityID,
+    LinkedEntityRecordID: userRecord.LinkedEntityRecordID,
+    __mj_CreatedAt: userRecord.__mj_CreatedAt,
+    __mj_UpdatedAt: userRecord.__mj_UpdatedAt,
+    FirstLast: userRecord.FirstLast,
+    EmployeeFirstLast: userRecord.EmployeeFirstLast,
+    EmployeeEmail: userRecord.EmployeeEmail,
+    EmployeeTitle: userRecord.EmployeeTitle,
+    EmployeeSupervisor: userRecord.EmployeeSupervisor,
+    EmployeeSupervisorEmail: userRecord.EmployeeSupervisorEmail,
+  };
+}
+
 export function RequireLoadedUser<T extends { ID?: string }>(
   user: T | null | undefined,
   email: string | undefined,

package/src/resolvers/meetings/meetingMutations.ts

@@ -305,6 +305,12 @@ export async function ExecuteUpdateMeeting(
   }
 }
 
+/**
+ * Starts a meeting for the `StartMeeting` mutation (`MeetingResolver`): marks it `Live`, ensures its Interaction, starts
+ * each agent participant in the room under an agent session created for it, starts an automatic recording, and mints the
+ * caller's client token. An agent that fails to start doesn't fail the meeting; the session created for it is closed
+ * (`Error`).
+ */
 export async function ExecuteStartMeeting(
   provider: IMetadataProvider,
   user: UserInfo,
@@ -343,12 +349,15 @@ export async function ExecuteStartMeeting(
     const agentParticipants = participants.filter((p) => p.Role === 'Agent' && p.AgentID);
 
     for (const ap of agentParticipants) {
+      // Set once this agent's session exists, so a start that fails after it was created can close it.
+      let createdSessionID: string | undefined;
       try {
         const createdSession = await sessionManager.CreateSession(
           { agentID: ap.AgentID!, userID: user.ID },
           user,
           provider,
         );
+        createdSessionID = createdSession.ID;
         await LiveKitAgentRoomCoordinator.Instance.StartAgentRoomSession({
           AgentSessionID: createdSession.ID,
           RoomName: meeting.RoomName,
@@ -357,9 +366,21 @@ export async function ExecuteStartMeeting(
           MetadataProvider: provider,
           TurnMode: 'Active',
           TurnAddressing: 'Auto',
+          // The session exists for this agent's time in the room alone: it closes when the agent leaves (the meeting is
+          // ended, everyone leaves, the agent is stopped), not when the janitor finds it idle.
+          Host: {
+            OnSessionEnded: async (reason) => {
+              await sessionManager.CloseSessionForEndedBridge(createdSession.ID, reason, user, provider);
+            },
+          },
         });
       } catch (agentErr) {
         LogError(`[MeetingResolver] Failed to start agent participant ${ap.AgentID} in room ${meeting.RoomName}: ${agentErr instanceof Error ? agentErr.message : String(agentErr)}`);
+        // The agent never joined, so the hook above never runs: close its session now (Error), not when the janitor finds
+        // it idle. The coordinator has already closed any model session the start opened (#5308).
+        if (createdSessionID) {
+          await sessionManager.CloseSessionForFailedStart(createdSessionID, user, provider);
+        }
       }
     }