@memberjunction/ai-core-plus

Shared type definitions and extended entity classes for the MemberJunction AI Framework. This package bridges the gap between the standalone @memberjunction/ai core and the full MJ entity system, providing types that are usable on both server and client. It defines prompt execution result types, agent execution types, system placeholder management, conversation utilities, and extended entity classes with additional computed properties.

Architecture

graph TD
    AI["@memberjunction/ai"]
    style AI fill:#2d6a9f,stroke:#1a4971,color:#fff

    CORE["@memberjunction/core"]
    style CORE fill:#2d6a9f,stroke:#1a4971,color:#fff

    CE["@memberjunction/core-entities"]
    style CE fill:#2d6a9f,stroke:#1a4971,color:#fff

    ACP["@memberjunction/ai-core-plus"]
    style ACP fill:#2d8659,stroke:#1a5c3a,color:#fff

    subgraph "ai-core-plus Modules"
        PT["Prompt Types<br/>AIPromptParams, AIPromptRunResult"]
        style PT fill:#7c5295,stroke:#563a6b,color:#fff

        AT["Agent Types<br/>ExecuteAgentParams, ExecuteAgentResult"]
        style AT fill:#7c5295,stroke:#563a6b,color:#fff

        SP["System Placeholders<br/>Date/Time, User Context"]
        style SP fill:#b8762f,stroke:#8a5722,color:#fff

        EXT["Extended Entities<br/>AIPrompt, AIModel, AIAgent"]
        style EXT fill:#2d6a9f,stroke:#1a4971,color:#fff

        CU["ConversationUtility"]
        style CU fill:#b8762f,stroke:#8a5722,color:#fff

        RF["Response Forms<br/>& UI Commands"]
        style RF fill:#7c5295,stroke:#563a6b,color:#fff
    end

    AI --> ACP
    CORE --> ACP
    CE --> ACP
    ACP --> PT
    ACP --> AT
    ACP --> SP
    ACP --> EXT
    ACP --> CU
    ACP --> RF

Installation

npm install @memberjunction/ai-core-plus

Key Exports

Prompt Types (prompt.types.ts)

Type / Class	Purpose
AIPromptParams	Full parameter set for prompt execution: prompt reference, data context, configuration, child prompts, streaming callbacks, cancellation, credential overrides, effort level, and more
AIPromptRunResult<T>	Generic result from prompt execution including raw/parsed output, token usage, cost, validation attempts, model selection info, and media references
ChildPromptParam	Links a child prompt to a placeholder in a parent template for hierarchical composition
AIModelSelectionInfo	Debugging info about which models were considered and why one was selected
ExecutionProgressCallback	Callback for real-time execution progress (template rendering, model selection, execution, validation)
ExecutionStreamingCallback	Callback for streaming content chunks during execution
ValidationAttempt	Detailed record of each validation attempt with attempt number, errors, and raw/parsed output
PromptRunMediaReference	Reference to generated media (image, audio, video) with metadata
ExecutionStatus	Status enum: 'Pending', 'Running', 'Completed', 'Failed', 'Cancelled'

AIPromptParams.PreRenderedChildTemplates (placeholder name → rendered child text) lets a caller that has already rendered the child prompts — via AIPromptRunner.RenderChildPromptTemplates — hand the text to ExecutePrompt so the children are not rendered twice; the loop agent uses it when relocating a volatile specialization into its trailing runtime-state message.

Agent Types (agent-types.ts)

Type / Class	Purpose
ExecuteAgentParams	Parameters for agent execution: agent reference, messages, conversation context, user scope, configuration presets, effort level, action changes, root-tree cumulative budgets (treeBudget, maxTreeSteps, maxTreeTokens, maxTreeCost, maxTreeDurationMs), and callbacks
AgentTreeBudget	Shared cumulative budget state (maxTreeSteps, maxTreeTokens, maxTreeCost, maxTreeDurationMs, totalSteps, totalTokens, totalCost, startedAtMs, breachedReason) propagated by reference across root and sub-agent execution trees
ExecuteAgentResult	Agent execution result with success status, output messages, actions performed, sub-agent requests, and model selection info
AgentContextData	Contextual data injected into agent prompts (notes, examples, data sources)
AgentConfiguration	Runtime configuration for an agent run (model overrides, effort level, max iterations)
UserScope	Multi-tenant scoping for agent memory with primary/secondary dimensions
AgentAction	Description of an action an agent wants to execute
AgentSubAgentRequest	Request from one agent to delegate work to a sub-agent
AgentChatMessage / AgentChatMessageMetadata	Chat messages with lifecycle metadata (expiration, compaction) and the volatileState flag marking the framework-authored trailing runtime-state fragment that provider drivers keep out of their cached prefix
MediaOutput	Media generated by an agent (modality, MIME type, data)
ActionChange / ActionChangeScope	Runtime action customization for multi-tenant scenarios
AgentPostRunCompactionConfig	Configuration for automatic post-run conversation compaction, scratchpad pruning, and background memory extraction (ExecuteAgentParams.compactAfterRun)

Consolidation Observability in ExecuteAgentResult

ExecuteAgentResult surfaces the agent run’s step list. As of v5.30.x, MemoryManagerAgent runs emit two new step types when its consolidation pipeline executes:

Step name	Cardinality	Notable payload fields
Process Consolidation Cluster	One per cluster identified	clusterSize, noteIds, shouldConsolidate, consolidatedNoteId, sourceNotesArchived, verificationPassed, entitiesChecked, entitiesMissing
Verify Consolidation Output	One per maintenance run	Phase-level summary of post-consolidation entity coverage check

Run-level payload additions include scoreDistribution, entityTriplesExtracted, decayScoreDistribution, protectedPreserved, ephemeralAccelerated, and triggerType ('forced' / 'time' / 'event' / 'count'). These flow through unchanged via ExecuteAgentResult.steps[*].outputData — consumers that already deserialize step output data will pick them up without code changes.

For pipeline mechanics, see @memberjunction/ai-agents.

Realtime Channel Contract v2 (realtime-channel-*.ts, realtime-session-policy.ts, agent-settings.ts, json-schema-subset.ts)

Framework-neutral types and pure functions shared by the browser runtime (@memberjunction/realtime-runtime) and the server (@memberjunction/ai-agents), so both make the same channel decisions from the same inputs.

Export	Purpose
RealtimeChannelDescriptor (+ RealtimeChannelNoun, RealtimeChannelVerb, RealtimeChannelEventSpec, RealtimeChannelDisplayPolicy, RealtimeChannelAvailability, RealtimeChannelExposure)	A channel’s self-description: what it holds (nouns), what it accepts (verbs with parameter schemas and InvokableBy), what it emits, how it appears ('open-on-start' | 'on-demand' | 'headless'), whether it is on for every session or opt-in, and the most the model may perceive of it ('none' | 'state' | 'pixels'). REALTIME_CHANNEL_CONTRACT_VERSION is 2.0.0; a descriptor synthesized for a channel that only implements the v1 members carries REALTIME_CHANNEL_LEGACY_CONTRACT_VERSION (1.0.0).
ResolveRealtimeChannelScope	Decides which candidate channels are in a session: code default → agent → app → host. A registry row’s IsActive = false is a master kill switch nothing overrides; a host adds channels but cannot lift an agent/app exclude. Also AccumulateRealtimeChannelsConfig (per-channel, most-specific-layer-wins folding of the cascade’s channels sections — not a plain deep merge, which would let an app’s exclude erase the agent’s), DeclaresNativeTools, SelectNativeChannelTools.
RealtimeChannelCandidate, RealtimeSessionClientPolicy, ParseRealtimeChannelCandidates, ParseRealtimeSessionClientPolicy	The two wire shapes of session policy negotiation at mint: the browser reports candidates (facts about code it owns), the server returns the resolved policy (channels in scope with their resolved display/config, plus the app/static client-tool tiers). Parsers are tolerant and capped; they never throw.
ParseAgentSettings, IAgentSettings	Tolerant parser + package-side mirror of Application.AgentSettings (kept in lockstep with metadata/entities/JSONType-interfaces/IAgentSettings.ts). Runtime code reads the raw column through this rather than the CodeGen-generated AgentSettingsObject, so a new settings field works before CodeGen next refreshes the generated copy. Includes Realtime.Channels (Include, Exclude, Config, DisplayPolicy).
ValidateJsonAgainstSchemaSubset	Small, dependency-free JSON Schema validator (type, enum, required, properties, additionalProperties: false, items, numeric/length/item bounds; unknown keywords ignored) returning one readable message per violation — what a channel verb’s parameters are checked against before it runs.
ResolveChannelExposure, ResolvePolicyExposure, MinExposure, ReadConfiguredMaxExposure, ZeroDataRetentionCeiling, DescribeExposureLimit, UserExposureReason, IsVerbWithheld, WithheldVerbs, DescribeWithheldVerb (realtime-channel-exposure.ts)	Exposure policy: how much of a channel the model may perceive without asking ('none' < 'state' < 'pixels'). effective = min(channel ceiling, agent cap, zero-data-retention ceiling, user choice); the first three are decided on the server and ride in RealtimeSessionClientPolicy (ResolvedRealtimeChannel.Exposure / ExposureLimits), the user’s choice is the browser’s and can only lower. The agent cap is channels.config.<Key>.maxExposure. requireZeroDataRetentionFor: ('state' | 'pixels')[] (cascade channels section; the union across layers) lowers exposure to just below the lowest listed level when the session model’s configuration does not declare Privacy.ZeroDataRetention: true (a requirement for 'state' therefore also withholds 'pixels'). DescribeExposureLimit words the downgrade for the agent. A verb whose RESULT carries channel data declares `ReturnsChannelData: ‘state'	'pixels’; IsVerbWithheld(verb, effective)is true when the effective exposure is below that level,WithheldVerbs(verbs, effective)lists them andDescribeWithheldVerb(…)words the refusal (the dispatcher'sexposure_restricted`). Policy, not redaction: the verb is refused whole. Pure, so both tiers share one definition.
ResolveAppClientToolMetadata, ClientToolMetadataFromDefinition	Resolve Application.AgentSettings.ClientTools references (ID then Name, priority ascending) against the tool-definition catalog into ClientToolMetadata, ready for ResolveClientTools.

FormatClientToolsForPrompt was removed: no caller ever adopted it (the async path words its own section; realtime renders compact signatures via FormatAppContextNote), and keeping a second, tempting wording with no caller is a liability.

System Placeholders (prompt.system-placeholders.ts)

The SystemPlaceholderManager automatically injects common values into all prompt templates:

• {{CurrentDate}}, {{CurrentTime}}, {{CurrentDateTime}} — Current date/time in user’s timezone
• {{CurrentTimezone}} — User’s timezone identifier
• {{UserName}}, {{UserEmail}}, {{UserFirstName}}, {{UserLastName}} — User context
• Custom placeholders can be registered at runtime

Extended Entity Classes

Class	Extends	Additional Properties
AIPromptEntityExtended	AIPromptEntity	Prompt category associations, template relationships
AIPromptCategoryEntityExtended	AIPromptCategoryEntity	Prompts array of child prompts
AIModelEntityExtended	AIModelEntity	ModelVendors array, vendor association helpers
AIAgentEntityExtended	AIAgentEntity	Actions, Notes arrays, agent relationships
AIAgentRunEntityExtended	AIAgentRunEntity	Extended run tracking
AIAgentRunStepEntityExtended	AIAgentRunStepEntity	Extended step tracking
AIPromptRunEntityExtended	AIPromptRunEntity	Extended prompt run tracking

Other Exports

Export	Purpose
ConversationUtility	Helper for creating, loading, and managing conversation records
AgentResponseForm	Structured response format definitions for agent outputs
ActionableCommand / AutomaticCommand	UI command types for agent-driven interfaces
AgentPayloadChangeRequest	Request to modify agent payload data during execution
ForEachOperation / WhileOperation	Loop operation definitions for flow-based agents

Usage

Prompt Execution Parameters

import { AIPromptParams, ChildPromptParam } from '@memberjunction/ai-core-plus';

const params = new AIPromptParams();
params.prompt = myPromptEntity;
params.data = { customerName: 'Acme Corp', orderCount: 42 };
params.contextUser = currentUser;
params.effortLevel = 75;

// Hierarchical prompt composition
params.childPrompts = [
    new ChildPromptParam(analysisParams, 'analysis'),
    new ChildPromptParam(summaryParams, 'summary')
];

// Model override at runtime
params.override = {
    modelId: 'specific-model-id',
    vendorId: 'specific-vendor-id'
};

// Force the runner to credential-check EVERY candidate model-vendor combination
// instead of short-circuiting at the first usable one. Default false — only enable
// for diagnostics that need a complete per-candidate availability report, since it
// runs a credential lookup for every configured model on the run.
params.forceFullModelEvaluation = true;

AIPromptParams field reference

Field	Type	Purpose
prompt	MJAIPromptEntityExtended	Required. The prompt to execute.
data	Record<string, unknown>	Data context merged into the template (user data overrides system placeholders).
templateData	Record<string, unknown>	Highest-priority template data (overrides data).
contextUser	UserInfo	Required server-side. The user the run executes as (security/audit).
configurationId	string	AI Configuration scoping model selection (supports inheritance chains).
conversationMessages	ChatMessage[]	Prior conversation turns appended after the rendered prompt.
templateMessageRole	'system' | 'user' | 'none'	Where the rendered prompt lands in the message array.
override	{ modelId?, vendorId? }	Runtime model/vendor override (highest selection precedence).
modelSelectionPrompt	MJAIPromptEntityExtended	Use a different prompt’s model config for selection.
forceFullModelEvaluation	boolean	Probe credentials for every candidate instead of short-circuiting (default false).
childPrompts	ChildPromptParam[]	Hierarchical template composition (children render first).
parentPromptRunId / agentRunId	string	Link this run to a parent prompt run / agent run.
rerunFromPromptRunID	string	Mark this run as a re-run of a prior one.
effortLevel	number	Reasoning effort override (highest precedence — see Effort Level Control).
additionalParameters	Record<string, any>	Override inference params (temperature/topP/seed/stopSequences/…) per request.
systemPromptOverride	string	Bypass template rendering and use this system prompt verbatim.
skipValidation	boolean	Skip output validation/parsing.
cleanValidationSyntax	boolean	Strip ?/*/:type markers from result keys (auto-on when OutputExample set).
attemptJSONRepair	boolean	Repair malformed JSON object output via JSON5 then LLM repair.
credentialId	string	Per-request credential override (highest credential precedence).
apiKeys	AIAPIKey[]	Legacy per-request API keys (used only if no credential bindings resolve).
CredentialScope	'Any' | 'RuntimeOnly'	Which credentials the run may spend. 'RuntimeOnly' allows only credentialId and apiKeys — no credential bindings, vendor default or environment keys. Also on ExecuteAgentParams, where BaseAgent carries it through the run.
nativeFileInputs	NativeFileInput[]	Files attached natively when the driver supports the modality (else text fallback).
cancellationToken	AbortSignal	Cooperative cancellation, checked at each phase.
onProgress / onStreaming	callbacks	Progress updates / streamed output chunks.
onPromptRunCreated	(promptRunId) => void	Fired with the AIPromptRun.ID as soon as the record is created (ID available immediately; the save is fire-and-forget).
verbose	boolean	Verbose status logging for this run.
maxErrorLength	number	Truncate long error messages (e.g. provider failed-generation dumps).
provider	IMetadataProvider	Metadata provider for multi-provider scenarios.

Agent Execution Parameters

import { ExecuteAgentParams, UserScope } from '@memberjunction/ai-core-plus';

const params: ExecuteAgentParams = {
    agent: myAgent,
    conversationMessages: [{ role: 'user', content: 'Analyze this data' }],
    contextUser: currentUser,
    userScope: {
        primaryEntityName: 'Organizations',
        primaryRecordId: orgId,
        secondary: { TeamID: teamId }
    },
    onProgress: (step) => console.log(`${step.step}: ${step.message}`)
};

Runtime Action Changes

import { ExecuteAgentParams, ActionChange } from '@memberjunction/ai-core-plus';

const params: ExecuteAgentParams = {
    agent: myAgent,
    conversationMessages: messages,
    actionChanges: [
        { scope: 'global', mode: 'add', actionIds: ['crm-action-id'] },
        { scope: 'all-subagents', mode: 'remove', actionIds: ['dangerous-action-id'] }
    ]
};

Message Lifecycle Management

import { ExecuteAgentParams, MessageLifecycleEvent } from '@memberjunction/ai-core-plus';

const params: ExecuteAgentParams = {
    agent: myAgent,
    conversationMessages: messages,
    messageExpirationOverride: {
        expirationTurns: 2,
        expirationMode: 'Compact',
        compactMode: 'First N Chars',
        compactLength: 500
    },
    onMessageLifecycle: (event: MessageLifecycleEvent) => {
        console.log(`[Turn ${event.turn}] ${event.type}: ${event.reason}`);
    }
};

Post-Run Compaction & Scratchpad Pruning (compactAfterRun)

import { ExecuteAgentParams } from '@memberjunction/ai-core-plus';

const params: ExecuteAgentParams = {
    agent: myAgent,
    conversationMessages: messages,
    contextUser: currentUser,
    compactAfterRun: {
        enabled: true,
        messageCountThreshold: 12,
        extractMemories: true,
        maxScratchpadNotes: 20
    }
};

Effort Level Control

MemberJunction supports a 1-100 scale for AI model reasoning effort. The resolution precedence is:

1. ExecuteAgentParams.effortLevel (runtime override, highest priority)
2. AIAgent.DefaultPromptEffortLevel (agent default)
3. AIPrompt.EffortLevel (prompt default)
4. Provider default behavior (lowest priority)

Provider mappings:

• OpenAI: 1-33 = low, 34-66 = medium, 67-100 = high
• Anthropic: Thinking mode with 25K-2M token budgets
• Groq: Experimental reasoning_effort parameter
• Gemini: Reasoning mode intensity

Dependencies

• @memberjunction/ai — Core AI abstractions
• @memberjunction/core — MJ framework core (Metadata, RunView, UserInfo)
• @memberjunction/core-entities — Generated entity classes
• @memberjunction/global — Class factory and global utilities
• @memberjunction/actions-base — Action framework base types
• @memberjunction/templates-base-types — Template engine base types
• date-fns / date-fns-tz — Date/time formatting and timezone support