@memberjunction/server 5.38.0 → 5.39.0

package/src/apolloServer/index.ts

@@ -15,6 +15,63 @@ import { SQLServerDataProvider } from '@memberjunction/sqlserver-dataprovider';
  * @param servers - HTTP server and WebSocket cleanup disposable
  * @param additionalPlugins - Optional additional plugins to merge with built-in plugins
  */
+/**
+ * Apollo plugin: log every Integration* GraphQL operation to stdout as
+ * structured JSON.  Lets operators tailing the MJAPI log see exactly which
+ * resolver the wizard / Explorer hit on each press, with arg names (values
+ * redacted for credentials).  Diagnostic-only — no behavior change.
+ *
+ * Emits two events per operation:
+ *   {"event":"gql.integration.request","method":"...","fieldName":"...","argNames":[...]}
+ *   {"event":"gql.integration.response","method":"...","fieldName":"...","durationMs":N,"hasErrors":bool}
+ *
+ * Filter from the log:
+ *   tail -f /tmp/mjapi.log | grep '"event":"gql\.integration\.'
+ */
+const integrationOperationTracer: ApolloServerPlugin = {
+  async requestDidStart(requestCtx) {
+    // Off by default — the plugin stays registered but emits nothing unless the
+    // MJ_INTEGRATION_TRACE debug flag is explicitly set. Avoids logging on every
+    // request in normal operation.
+    if (process.env.MJ_INTEGRATION_TRACE !== 'true') return undefined;
+    const opName = requestCtx.request.operationName ?? 'anonymous';
+    const query = requestCtx.request.query ?? '';
+    // Lightweight match — fire only for operations that touch an Integration
+    // resolver field.  Avoid logging every Color / User / Task query.
+    if (!query.includes('Integration')) return undefined;
+    const startedAt = Date.now();
+    return {
+      async willSendResponse(rc) {
+        // Walk the fields the operation queried; only those starting with
+        // "Integration" matter.  Variables surfaced as keys only.
+        const op = rc.operation;
+        if (!op) return;
+        const integrationFields: string[] = [];
+        for (const sel of op.selectionSet.selections) {
+          if (sel.kind === 'Field' && sel.name.value.startsWith('Integration')) {
+            integrationFields.push(sel.name.value);
+          }
+        }
+        if (integrationFields.length === 0) return;
+        const argNames = Object.keys(rc.request.variables ?? {});
+        const durationMs = Date.now() - startedAt;
+        const hasErrors = !!(rc.response.body.kind === 'single' && rc.response.body.singleResult.errors?.length);
+        for (const field of integrationFields) {
+          console.log(JSON.stringify({
+            ts: new Date().toISOString(),
+            event: 'gql.integration.response',
+            operationName: opName,
+            method: field,
+            argNames,
+            durationMs,
+            hasErrors,
+          }));
+        }
+      },
+    };
+  },
+};
+
 const buildApolloServer = (
   configOverride: ApolloServerOptions<AppContext>,
   { httpServer, serverCleanup }: { httpServer: Server; serverCleanup: Disposable },
@@ -22,6 +79,7 @@ const buildApolloServer = (
 ) => {
   const builtInPlugins: ApolloServerPlugin[] = [
     ApolloServerPluginDrainHttpServer({ httpServer }),
+    integrationOperationTracer,
     {
       async serverWillStart() {
         return {

package/src/config.ts

@@ -205,6 +205,21 @@ const cacheSettingsSchema = z.object({
   verboseLogging: z.boolean().optional().default(false),
 });
 
+const loggingSettingsSchema = z.object({
+  graphql: z.object({
+    /**
+     * When true, emit a redacted variables block per root resolver call via the
+     * type-graphql global middleware. Default: false in all environments regardless
+     * of NODE_ENV. Env override: `MJ_LOG_GRAPHQL_VARIABLES`.
+     *
+     * SECURITY: this is an opt-in verbose-echo path for developers debugging locally.
+     * The always-on request log line in `context.ts` does NOT emit variables — that
+     * is the load-bearing leak fix. This flag is additive on top of the always-on log.
+     */
+    logVariables: z.boolean().optional().default(false),
+  }).optional().default({}),
+});
+
 const feedbackGithubSettingsSchema = z.object({
   owner: z.string().optional(),
   repo: z.string().optional(),
@@ -236,6 +251,7 @@ const configInfoSchema = z.object({
   multiTenancy: multiTenancySchema.optional().default({}),
   serverExtensions: z.array(serverExtensionSchema).optional().default([]),
   cacheSettings: cacheSettingsSchema.optional().default({}),
+  loggingSettings: loggingSettingsSchema.optional().default({}),
   feedbackSettings: feedbackSettingsSchema.optional().default({}),
 
   apiKey: z.string().optional(),
@@ -284,6 +300,7 @@ export type QueryDialectConfig = z.infer<typeof queryDialectSchema>;
 export type MultiTenancyConfig = z.infer<typeof multiTenancySchema>;
 export type ServerExtensionConfig = z.infer<typeof serverExtensionSchema>;
 export type CacheSettingsConfig = z.infer<typeof cacheSettingsSchema>;
+export type LoggingSettingsConfig = z.infer<typeof loggingSettingsSchema>;
 export type FeedbackGithubSettingsConfig = z.infer<typeof feedbackGithubSettingsSchema>;
 export type FeedbackSettingsConfig = z.infer<typeof feedbackSettingsSchema>;
 export type ConfigInfo = z.infer<typeof configInfoSchema>;
@@ -421,6 +438,16 @@ export const DEFAULT_SERVER_CONFIG: Partial<ConfigInfo> = {
     verboseLogging: false,
   },
 
+  // Logging settings defaults — variables logging is always off unless the operator
+  // sets MJ_LOG_GRAPHQL_VARIABLES=true (or sets logVariables in mj.config.cjs).
+  // NOTE: this only governs the opt-in verbose-echo middleware. The always-on request
+  // log in context.ts already strips variables unconditionally.
+  loggingSettings: {
+    graphql: {
+      logVariables: parseBooleanEnv(process.env.MJ_LOG_GRAPHQL_VARIABLES),
+    },
+  },
+
   // Auth providers (environment-driven)
   authProviders: [
     // Microsoft Azure AD / Entra ID

package/src/context.ts

@@ -9,6 +9,7 @@ import { getSigningKeys, getSystemUser, getValidationOptions, verifyUserRecord,
 import { TokenExpiredError, AuthProviderFactory } from '@memberjunction/auth-providers';
 import { authCache } from './cache.js';
 import { userEmailMap, apiKey, mj_core_schema } from './config.js';
+import { buildBoundaryLogPayload } from './logging/boundaryLogPayload.js';
 import { DataSourceInfo, UserPayload } from './types.js';
 import { GetReadOnlyDataSource, GetReadWriteDataSource } from './util.js';
 import { v4 as uuidv4 } from 'uuid';
@@ -21,24 +22,6 @@ import { UUIDsEqual } from '@memberjunction/global';
 import { resolveDbPlatformFromEnv } from '@memberjunction/generic-database-provider';
 import { GetAPIKeyEngine } from '@memberjunction/api-keys';
 
-/**
- * Renders a value for one-line console logging without Node's `[Object]` truncation.
- * Arrays keep their structure; non-array objects collapse to JSON, truncated at `maxLen`.
- * Objects whose JSON exceeds `maxLen` and contain nested structure are recursed into so
- * outer keys remain visible.
- */
-function shortenForLog(value: unknown, maxLen = 300): unknown {
-  if (value === null || typeof value !== 'object') return value;
-  if (Array.isArray(value)) return value.map((v) => shortenForLog(v, maxLen));
-  const json = JSON.stringify(value);
-  if (json.length <= maxLen) return json;
-  const result: Record<string, unknown> = {};
-  for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
-    result[k] = shortenForLog(v, maxLen);
-  }
-  return result;
-}
-
 const verifyAsync = async (issuer: string, token: string): Promise<jwt.JwtPayload> =>
   new Promise((resolve, reject) => {
     const options = getValidationOptions(issuer);
@@ -342,7 +325,7 @@ export const contextFunction =
     const reqAny = req as any;
     const operationName: string | undefined = reqAny.body?.operationName;
     if (operationName !== 'IntrospectionQuery') {
-      console.dir({ operationName, variables: shortenForLog(reqAny.body?.variables) }, { depth: null, breakLength: 200 });
+      console.dir(buildBoundaryLogPayload(operationName), { depth: null, breakLength: 200 });
     }
 
     // Auth already happened in the unified auth middleware — just read the result

package/src/generated/generated.ts

@@ -7593,6 +7593,12 @@ each time the agent processes a prompt step.`})
     @MaxLength(36)
     CompanyID?: string;
         
+    @Field(() => Int, {nullable: true, description: `Total input tokens served from the AI provider's prompt cache (cache reads / hits) across this agent run, summed from child prompt runs' TokensCacheReadRollup and sub-agent runs' TotalCacheReadTokensUsed. Counts only; the cost impact (cache reads are billed at a steep discount) is reflected in TotalCost. The cache counterpart of TotalPromptTokensUsed.`}) 
+    TotalCacheReadTokensUsed?: number;
+        
+    @Field(() => Int, {nullable: true, description: `Total input tokens written to the AI provider's prompt cache (cache writes / creation) across this agent run, summed from child prompt runs' TokensCacheWriteRollup and sub-agent runs' TotalCacheWriteTokensUsed. Populated for providers that bill cache creation (e.g. Anthropic); 0 or NULL otherwise. The cache counterpart of TotalCompletionTokensUsed.`}) 
+    TotalCacheWriteTokensUsed?: number;
+        
     @Field({nullable: true}) 
     @MaxLength(255)
     Agent?: string;
@@ -7814,6 +7820,12 @@ export class CreateMJAIAgentRunInput {
     @Field({ nullable: true })
     CompanyID: string | null;
 
+    @Field(() => Int, { nullable: true })
+    TotalCacheReadTokensUsed: number | null;
+
+    @Field(() => Int, { nullable: true })
+    TotalCacheWriteTokensUsed: number | null;
+
     @Field(() => RestoreContextInput, { nullable: true })
     RestoreContext___?: RestoreContextInput;
 }
@@ -7956,6 +7968,12 @@ export class UpdateMJAIAgentRunInput {
     @Field({ nullable: true })
     CompanyID?: string | null;
 
+    @Field(() => Int, { nullable: true })
+    TotalCacheReadTokensUsed?: number | null;
+
+    @Field(() => Int, { nullable: true })
+    TotalCacheWriteTokensUsed?: number | null;
+
     @Field(() => [KeyValuePairInput], { nullable: true })
     OldValues___?: KeyValuePairInput[];
 
@@ -12243,6 +12261,12 @@ export class MJAIModelCost_ {
     @Field() 
     _mj__UpdatedAt: Date;
         
+    @Field(() => Float, {nullable: true, description: `Optional price per unit for input tokens served from the AI provider's prompt cache (cache reads / hits), expressed in the same currency and UnitType (e.g. per 1M tokens) as InputPricePerUnit. When NULL, cache-read tokens are priced at InputPricePerUnit. Cache reads are usually far cheaper than uncached input (e.g. ~0.1x for Anthropic/Gemini, ~0.5x for OpenAI).`}) 
+    CacheReadPricePerUnit?: number;
+        
+    @Field(() => Float, {nullable: true, description: `Optional price per unit for input tokens written to the AI provider's prompt cache (cache writes / creation), expressed in the same currency and UnitType as InputPricePerUnit. When NULL, cache-write tokens are priced at InputPricePerUnit. Populated for providers that bill cache creation separately (e.g. Anthropic, ~1.25x input); leave NULL for providers that do not (OpenAI, Gemini), which also report 0 cache-write tokens.`}) 
+    CacheWritePricePerUnit?: number;
+        
     @Field() 
     @MaxLength(50)
     Model: string;
@@ -12305,6 +12329,12 @@ export class CreateMJAIModelCostInput {
     @Field({ nullable: true })
     Comments: string | null;
 
+    @Field(() => Float, { nullable: true })
+    CacheReadPricePerUnit: number | null;
+
+    @Field(() => Float, { nullable: true })
+    CacheWritePricePerUnit: number | null;
+
     @Field(() => RestoreContextInput, { nullable: true })
     RestoreContext___?: RestoreContextInput;
 }
@@ -12354,6 +12384,12 @@ export class UpdateMJAIModelCostInput {
     @Field({ nullable: true })
     Comments?: string | null;
 
+    @Field(() => Float, { nullable: true })
+    CacheReadPricePerUnit?: number | null;
+
+    @Field(() => Float, { nullable: true })
+    CacheWritePricePerUnit?: number | null;
+
     @Field(() => [KeyValuePairInput], { nullable: true })
     OldValues___?: KeyValuePairInput[];
 
@@ -15236,6 +15272,18 @@ export class MJAIPromptRun_ {
     @Field({nullable: true, description: `The assistant prefill text that was used during this prompt execution. Records whether native prefill or fallback was applied. NULL means no prefill was used.`}) 
     AssistantPrefill?: string;
         
+    @Field(() => Int, {nullable: true, description: `Number of input tokens served from the AI provider's prompt cache (a cache READ / hit) for this run, as reported by the provider. Counts only; no cost is derived here. NULL if the provider did not report cache reads or caching did not engage. Distinct from CacheHit/CacheKey, which track MemberJunction's own result cache.`}) 
+    TokensCacheRead?: number;
+        
+    @Field(() => Int, {nullable: true, description: `Number of input tokens written to the AI provider's prompt cache (a cache WRITE / creation) for this run, as reported by the provider. Populated for providers that report cache writes (e.g. Anthropic cache_creation_input_tokens); NULL or 0 for providers that do not bill/report writes (OpenAI, Gemini, Groq, Cerebras). Counts only; no cost is derived here.`}) 
+    TokensCacheWrite?: number;
+        
+    @Field(() => Int, {nullable: true, description: `Rollup of TokensCacheRead across this prompt run and all of its descendant prompt runs (e.g. the individual attempts behind a parallel / multi-attempt / failover consolidation). For a leaf run this equals TokensCacheRead. Use this (not TokensCacheRead) when aggregating cache reads up a prompt-run or agent-run hierarchy so fan-out provider calls are not under-counted.`}) 
+    TokensCacheReadRollup?: number;
+        
+    @Field(() => Int, {nullable: true, description: `Rollup of TokensCacheWrite across this prompt run and all of its descendant prompt runs. For a leaf run this equals TokensCacheWrite. Mirrors TokensUsedRollup/TokensPromptRollup; populated for providers that report cache writes (e.g. Anthropic), otherwise 0 or NULL.`}) 
+    TokensCacheWriteRollup?: number;
+        
     @Field() 
     @MaxLength(255)
     Prompt: string;
@@ -15563,6 +15611,18 @@ export class CreateMJAIPromptRunInput {
     @Field({ nullable: true })
     AssistantPrefill: string | null;
 
+    @Field(() => Int, { nullable: true })
+    TokensCacheRead: number | null;
+
+    @Field(() => Int, { nullable: true })
+    TokensCacheWrite: number | null;
+
+    @Field(() => Int, { nullable: true })
+    TokensCacheReadRollup: number | null;
+
+    @Field(() => Int, { nullable: true })
+    TokensCacheWriteRollup: number | null;
+
     @Field(() => RestoreContextInput, { nullable: true })
     RestoreContext___?: RestoreContextInput;
 }
@@ -15822,6 +15882,18 @@ export class UpdateMJAIPromptRunInput {
     @Field({ nullable: true })
     AssistantPrefill?: string | null;
 
+    @Field(() => Int, { nullable: true })
+    TokensCacheRead?: number | null;
+
+    @Field(() => Int, { nullable: true })
+    TokensCacheWrite?: number | null;
+
+    @Field(() => Int, { nullable: true })
+    TokensCacheReadRollup?: number | null;
+
+    @Field(() => Int, { nullable: true })
+    TokensCacheWriteRollup?: number | null;
+
     @Field(() => [KeyValuePairInput], { nullable: true })
     OldValues___?: KeyValuePairInput[];
 
@@ -44228,7 +44300,7 @@ export class MJEntityField_ {
     @MaxLength(20)
     ValueListType: string;
         
-    @Field({nullable: true, description: `Defines extended behaviors for a field such as for Email, Web URLs, Code, etc.`}) 
+    @Field({nullable: true, description: `Defines extended behaviors for a field such as Email, Web URLs, Code, Markdown, HTML, and Icon. When set to 'Icon', the field's values are treated as icon CSS classes (e.g. Font Awesome) for per-row display in the UI.`}) 
     @MaxLength(50)
     ExtendedType?: string;
         
@@ -49627,6 +49699,10 @@ export class MJIntegrationObjectField_ {
     @Field(() => Boolean, {description: `When true, this field was dynamically discovered by IntrospectSchema and is not defined in static connector metadata.`}) 
     IsCustom: boolean;
         
+    @Field({description: `Provenance of this IntegrationObjectField row: Declared (from static research/docs), Discovered (from runtime API introspection), Custom (customer-defined custom field, e.g., HubSpot custom property on standard object). Drives merge precedence — discovered/runtime wins for type/constraints; declared wins for description/label/sequence/category.`}) 
+    @MaxLength(20)
+    MetadataSource: string;
+        
     @Field() 
     @MaxLength(255)
     IntegrationObject: string;
@@ -49708,6 +49784,9 @@ export class CreateMJIntegrationObjectFieldInput {
     @Field(() => Boolean, { nullable: true })
     IsCustom?: boolean;
 
+    @Field({ nullable: true })
+    MetadataSource?: string;
+
     @Field(() => RestoreContextInput, { nullable: true })
     RestoreContext___?: RestoreContextInput;
 }
@@ -49784,6 +49863,9 @@ export class UpdateMJIntegrationObjectFieldInput {
     @Field(() => Boolean, { nullable: true })
     IsCustom?: boolean;
 
+    @Field({ nullable: true })
+    MetadataSource?: string;
+
     @Field(() => [KeyValuePairInput], { nullable: true })
     OldValues___?: KeyValuePairInput[];
 
@@ -49963,6 +50045,59 @@ export class MJIntegrationObject_ {
     @Field(() => Boolean, {description: `When true, this object was dynamically discovered by IntrospectSchema and is not defined in static connector metadata.`}) 
     IsCustom: boolean;
         
+    @Field({nullable: true, description: `HTTP path template for create operations. Generic CRUD in BaseRESTIntegrationConnector substitutes parent IDs into {var} placeholders. NULL means create not supported via metadata-driven path.`}) 
+    CreateAPIPath?: string;
+        
+    @Field({nullable: true, description: `HTTP method for create (typically POST). NULL means create not supported via metadata-driven path.`}) 
+    @MaxLength(20)
+    CreateMethod?: string;
+        
+    @Field({nullable: true, description: `Request body shape for create: flat (top-level fields), wrapped (under CreateBodyKey), or literal (connector overrides CreateRecord and supplies own body).`}) 
+    @MaxLength(50)
+    CreateBodyShape?: string;
+        
+    @Field({nullable: true, description: `Wrapper key for create body when CreateBodyShape=wrapped. Example: 'member' for YourMembership which wraps body as {member:{...}}.`}) 
+    @MaxLength(100)
+    CreateBodyKey?: string;
+        
+    @Field({nullable: true, description: `Where the created record ID is found in the create response: path (URL of returned Location header), body (parsed from JSON response), header (specific named header).`}) 
+    @MaxLength(20)
+    CreateIDLocation?: string;
+        
+    @Field({nullable: true, description: `HTTP path template for update operations. Typically contains {ID} placeholder substituted with the record ExternalID at runtime.`}) 
+    UpdateAPIPath?: string;
+        
+    @Field({nullable: true, description: `HTTP method for update (typically PATCH or PUT).`}) 
+    @MaxLength(20)
+    UpdateMethod?: string;
+        
+    @Field({nullable: true, description: `Request body shape for update: flat | wrapped | literal. See CreateBodyShape.`}) 
+    @MaxLength(50)
+    UpdateBodyShape?: string;
+        
+    @Field({nullable: true, description: `Wrapper key for update body when UpdateBodyShape=wrapped.`}) 
+    @MaxLength(100)
+    UpdateBodyKey?: string;
+        
+    @Field({nullable: true, description: `For update: where the target record ID is located in the request — typically 'path' (substituted into UpdateAPIPath URL template).`}) 
+    @MaxLength(20)
+    UpdateIDLocation?: string;
+        
+    @Field({nullable: true, description: `HTTP path template for delete operations. Typically contains {ID} placeholder. NULL means delete not supported via metadata-driven path. (Existing DeleteMethod column carries the verb.)`}) 
+    DeleteAPIPath?: string;
+        
+    @Field({nullable: true, description: `For delete: where the target record ID is located — typically 'path'.`}) 
+    @MaxLength(20)
+    DeleteIDLocation?: string;
+        
+    @Field({nullable: true, description: `Vendor field name marking "last changed" — drives incremental sync filter when SupportsIncrementalSync=1. The exact filter syntax (e.g., $filter=Modified gt {value} or modified_since={value}) lives in Configuration.incrementalFilterFormat. Provable-only: leave NULL if docs do not name a watermark field.`}) 
+    @MaxLength(255)
+    IncrementalWatermarkField?: string;
+        
+    @Field({description: `Provenance of this IntegrationObject row: Declared (from static research/docs), Discovered (from runtime API introspection like Salesforce /describe), Custom (genuinely customer-created, e.g., HubSpot custom objects). Drives merge precedence in IntegrationSchemaSync.`}) 
+    @MaxLength(20)
+    MetadataSource: string;
+        
     @Field() 
     @MaxLength(100)
     Integration: string;
@@ -50043,6 +50178,48 @@ export class CreateMJIntegrationObjectInput {
     @Field(() => Boolean, { nullable: true })
     IsCustom?: boolean;
 
+    @Field({ nullable: true })
+    CreateAPIPath: string | null;
+
+    @Field({ nullable: true })
+    CreateMethod: string | null;
+
+    @Field({ nullable: true })
+    CreateBodyShape: string | null;
+
+    @Field({ nullable: true })
+    CreateBodyKey: string | null;
+
+    @Field({ nullable: true })
+    CreateIDLocation: string | null;
+
+    @Field({ nullable: true })
+    UpdateAPIPath: string | null;
+
+    @Field({ nullable: true })
+    UpdateMethod: string | null;
+
+    @Field({ nullable: true })
+    UpdateBodyShape: string | null;
+
+    @Field({ nullable: true })
+    UpdateBodyKey: string | null;
+
+    @Field({ nullable: true })
+    UpdateIDLocation: string | null;
+
+    @Field({ nullable: true })
+    DeleteAPIPath: string | null;
+
+    @Field({ nullable: true })
+    DeleteIDLocation: string | null;
+
+    @Field({ nullable: true })
+    IncrementalWatermarkField: string | null;
+
+    @Field({ nullable: true })
+    MetadataSource?: string;
+
     @Field(() => RestoreContextInput, { nullable: true })
     RestoreContext___?: RestoreContextInput;
 }
@@ -50116,6 +50293,48 @@ export class UpdateMJIntegrationObjectInput {
     @Field(() => Boolean, { nullable: true })
     IsCustom?: boolean;
 
+    @Field({ nullable: true })
+    CreateAPIPath?: string | null;
+
+    @Field({ nullable: true })
+    CreateMethod?: string | null;
+
+    @Field({ nullable: true })
+    CreateBodyShape?: string | null;
+
+    @Field({ nullable: true })
+    CreateBodyKey?: string | null;
+
+    @Field({ nullable: true })
+    CreateIDLocation?: string | null;
+
+    @Field({ nullable: true })
+    UpdateAPIPath?: string | null;
+
+    @Field({ nullable: true })
+    UpdateMethod?: string | null;
+
+    @Field({ nullable: true })
+    UpdateBodyShape?: string | null;
+
+    @Field({ nullable: true })
+    UpdateBodyKey?: string | null;
+
+    @Field({ nullable: true })
+    UpdateIDLocation?: string | null;
+
+    @Field({ nullable: true })
+    DeleteAPIPath?: string | null;
+
+    @Field({ nullable: true })
+    DeleteIDLocation?: string | null;
+
+    @Field({ nullable: true })
+    IncrementalWatermarkField?: string | null;
+
+    @Field({ nullable: true })
+    MetadataSource?: string;
+
     @Field(() => [KeyValuePairInput], { nullable: true })
     OldValues___?: KeyValuePairInput[];
 
@@ -65639,6 +65858,9 @@ export class MJScheduledJob_ {
     @Field() 
     _mj__UpdatedAt: Date;
         
+    @Field(() => Boolean, {description: `When true AND LastRunAt IS NULL, the scheduler sets NextRunAt to now() instead of the next cron tick on initialization, so the job runs on the next polling cycle. Useful for newly-seeded jobs that should not wait up to a full cron interval before their first execution.`}) 
+    RunImmediatelyIfNeverRun: boolean;
+        
     @Field() 
     @MaxLength(100)
     JobType: string;
@@ -65742,6 +65964,9 @@ export class CreateMJScheduledJobInput {
     @Field({ nullable: true })
     ConcurrencyMode?: string;
 
+    @Field(() => Boolean, { nullable: true })
+    RunImmediatelyIfNeverRun?: boolean;
+
     @Field(() => RestoreContextInput, { nullable: true })
     RestoreContext___?: RestoreContextInput;
 }
@@ -65830,6 +66055,9 @@ export class UpdateMJScheduledJobInput {
     @Field({ nullable: true })
     ConcurrencyMode?: string;
 
+    @Field(() => Boolean, { nullable: true })
+    RunImmediatelyIfNeverRun?: boolean;
+
     @Field(() => [KeyValuePairInput], { nullable: true })
     OldValues___?: KeyValuePairInput[];
 
@@ -69621,6 +69849,10 @@ export class MJTagSynonym_ {
     @Field() 
     _mj__UpdatedAt: Date;
         
+    @Field({description: `Approval state of the synonym. Active = resolves to its tag during classification. Pending = proposed (e.g. by the LLM or a bulk import) and awaiting human review; does not resolve until approved. Rejected = reviewed and declined; retained for audit and to suppress re-proposal.`}) 
+    @MaxLength(20)
+    Status: string;
+        
     @Field() 
     @MaxLength(255)
     Tag: string;
@@ -69644,6 +69876,9 @@ export class CreateMJTagSynonymInput {
     @Field({ nullable: true })
     Source?: string;
 
+    @Field({ nullable: true })
+    Status?: string;
+
     @Field(() => RestoreContextInput, { nullable: true })
     RestoreContext___?: RestoreContextInput;
 }
@@ -69666,6 +69901,9 @@ export class UpdateMJTagSynonymInput {
     @Field({ nullable: true })
     Source?: string;
 
+    @Field({ nullable: true })
+    Status?: string;
+
     @Field(() => [KeyValuePairInput], { nullable: true })
     OldValues___?: KeyValuePairInput[];
 

package/src/generic/FireAndForgetHeartbeat.ts

@@ -0,0 +1,85 @@
+import { PubSubEngine } from 'type-graphql';
+import { LogError } from '@memberjunction/core';
+import { PUSH_STATUS_UPDATES_TOPIC } from './PushStatusResolver.js';
+
+/** Default cadence for fire-and-forget liveness pulses (5 minutes). */
+export const DEFAULT_PULSE_INTERVAL_MS = 5 * 60 * 1000;
+
+/** The `type` discriminator carried by liveness pulse messages. */
+export const HEARTBEAT_MESSAGE_TYPE = 'Heartbeat';
+
+/**
+ * Lightweight status snapshot included in an enriched pulse so the client can
+ * correlate the pulse with a run record and surface a coarse "still running"
+ * signal. Read from the in-memory run entity — never a DB query.
+ */
+export interface PulseStatus {
+    /** Primary key of the persisted run record (AIAgentRun, TestRun, TestSuiteRun). */
+    runId?: string;
+    /** Current run status, e.g. 'Running'. */
+    status?: string;
+    /** Optional human-readable current step for UI display. */
+    currentStep?: string;
+}
+
+/** Handle returned by {@link startLivenessPulse}; call `stop()` when the work settles. */
+export interface LivenessPulseHandle {
+    stop(): void;
+}
+
+export interface LivenessPulseOptions {
+    /** PubSub engine used to publish on the shared push-status topic. */
+    pubSub: PubSubEngine;
+    /** Session the client is subscribed on (used by the subscription filter). */
+    sessionId: string;
+    /** Resolver label echoed in the message envelope (e.g. 'RunAIAgentResolver'). */
+    resolver: string;
+    /** Pulse cadence in ms. Defaults to {@link DEFAULT_PULSE_INTERVAL_MS}. */
+    intervalMs?: number;
+    /**
+     * Optional cheap status reader invoked on each tick. Should read from an
+     * in-memory ref, not the database. Errors are swallowed so a transient read
+     * never kills the pulse loop.
+     */
+    readStatus?: () => PulseStatus | undefined;
+}
+
+/**
+ * Publishes a periodic liveness pulse on {@link PUSH_STATUS_UPDATES_TOPIC} while a
+ * fire-and-forget background operation runs. Each pulse resets the client's idle
+ * timer, so a long-but-active operation never spuriously times out. The pulse
+ * stops when the caller invokes `stop()` (typically in the background promise's
+ * `finally` block).
+ *
+ * The envelope matches the resolvers' existing push-status messages
+ * (`{ message: JSON.stringify({ resolver, type, status, data }), sessionId }`),
+ * so the client receives it through the same subscription with no special parsing.
+ */
+export function startLivenessPulse(options: LivenessPulseOptions): LivenessPulseHandle {
+    const { pubSub, sessionId, resolver, readStatus } = options;
+    const intervalMs = options.intervalMs ?? DEFAULT_PULSE_INTERVAL_MS;
+
+    const timer = setInterval(() => {
+        let data: PulseStatus | undefined;
+        try {
+            data = readStatus?.();
+        } catch (e) {
+            // A status read failure must not break the liveness loop.
+            LogError(`[LivenessPulse:${resolver}] readStatus failed: ${(e as Error).message}`);
+        }
+
+        pubSub.publish(PUSH_STATUS_UPDATES_TOPIC, {
+            message: JSON.stringify({
+                resolver,
+                type: HEARTBEAT_MESSAGE_TYPE,
+                status: 'ok',
+                data: data ?? {},
+            }),
+            sessionId,
+        });
+    }, intervalMs);
+
+    return {
+        stop: () => clearInterval(timer),
+    };
+}