@memberjunction/ai-agents 6.1.0-edge.6 → 6.1.0

package/dist/realtime/realtime-client-session-service.js

@@ -9,14 +9,14 @@
  *
  * 1. {@link RealtimeClientSessionService.PrepareClientSession} — resolves the Realtime model,
  *    assembles the companion system prompt (co-agent prompt + target identity + history + memory),
- *    builds the stable, target-independent tool set (always including `invoke-target-agent`), and
+ *    builds the realtime tool set (always including `invoke-target-agent`, plus allowed direct actions on dynamic-toolset drivers), and
  *    asks the model to mint a {@link ClientRealtimeSessionConfig} (ephemeral token + provider
  *    session config) the browser applies verbatim.
  * 2. {@link RealtimeClientSessionService.ExecuteRelayedTool} — executes a single tool call the
  *    browser relayed, routing it through the shared {@link RealtimeToolBroker} so the result is
  *    byte-for-byte identical to the server-bridged path. `invoke-target-agent` delegates to the
- *    target agent via {@link AgentRunner.RunAgent}; every other tool returns a structured
- *    "not available" result for now (action wiring is a later phase).
+ *    target agent via {@link AgentRunner.RunAgent}; allowed direct actions execute via
+ *    {@link ActionEngineServer.Instance.RunAction}; other tools return a structured "not available" result.
  *
  * **Why this duplicates BaseAgent.** The private helpers in `BaseAgent.executeRealtimeSession`
  * (model resolution, companion-prompt assembly, target-agent resolution, delegation) are the
@@ -31,14 +31,16 @@
  */
 import { LogError, LogStatus, RunView } from '@memberjunction/core';
 import { MJGlobal, MJLruCache, UUIDsEqual, EscapeSQLString } from '@memberjunction/global';
+import { ActionEngineServer } from '@memberjunction/actions';
+import { RunActionParams } from '@memberjunction/actions-base';
 import { BaseRealtimeModel, GetAIAPIKey } from '@memberjunction/ai';
 import { FormatAppContextNote } from '@memberjunction/ai-core-plus';
 import { AIEngine } from '@memberjunction/aiengine';
 import { AgentMemoryContextBuilder } from '../agent-memory-context-builder.js';
 import { AgentRunner } from '../AgentRunner.js';
-import { RealtimeToolBroker, INVOKE_TARGET_AGENT_TOOL_NAME, BuildRealtimeAgentFraming } from './realtime-tool-broker.js';
+import { RealtimeToolBroker, INVOKE_TARGET_AGENT_TOOL_NAME, INVOKE_TARGET_AGENT_DESCRIPTION, BuildRealtimeAgentFraming } from './realtime-tool-broker.js';
 import { NARRATION_PROMPT_NAME, LEGACY_NARRATION_PROMPT_NAME, ResolveNarrationInstructionsTemplate } from './realtime-narration.js';
-import { BuildVoiceMannerSection, BuildAppRealtimeOverridesJson, DeepMergeConfigs, GetModelCatalogSessionSettings, GetDisclosureForTarget, GetNarrationPaceMs, GetProviderVoiceSettings, GetSessionTuningSettings, ResolveEffectiveRealtimeConfig, MatchProviderVoiceSettings } from './realtime-coagent-config.js';
+import { BuildVoiceMannerSection, BuildAppRealtimeOverridesJson, DeepMergeConfigs, GetModelCatalogSessionSettings, GetDisclosureForTarget, GetNarrationPaceMs, GetProviderVoiceSettings, GetSessionTuningSettings, ResolveEffectiveRealtimeConfig, MatchProviderVoiceSettings, GetDirectActionsConfig, IsActionAllowedForDirectInvocation } from './realtime-coagent-config.js';
 import { SelectRealtimeVendorForModel } from './realtime-vendor-resolution.js';
 /**
  * Logs when a configuration authored per-provider voice settings but NONE matched the vendor that
@@ -77,6 +79,32 @@ export function WarnOnUnmatchedProviderVoice(effectiveConfig, driverClass, surfa
         `driver '${driverClass ?? 'unknown'}' — none matched, so those settings were dropped. Author ` +
         'realtime.voice.default.voice to carry a voice to whichever vendor runs.');
 }
+/**
+ * Sanitizes an action or tool name to conform to provider wire constraints
+ * (e.g. OpenAI function naming: ^[a-zA-Z0-9_-]{1,64}$).
+ *
+ * Replaces non-alphanumeric/hyphen/underscore characters with underscores,
+ * collapses consecutive runs of underscores into a single underscore, and
+ * truncates to 64 characters.
+ *
+ * @param name The original action or tool name.
+ * @returns The sanitized wire-safe name.
+ */
+export function SanitizeWireToolName(name) {
+    return name
+        .replace(/[^a-zA-Z0-9_-]/g, '_')
+        .replace(/_+/g, '_')
+        .slice(0, 64);
+}
+/**
+ * Sentinel error thrown when action tool arguments are present but cannot be parsed or are not a JSON object.
+ */
+export class ToolArgumentsError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ToolArgumentsError';
+    }
+}
 /**
  * Server-agnostic service that prepares a client-direct realtime session and executes the tool
  * calls the browser relays back. Constructed per-request (a normal injectable service — NOT a
@@ -87,6 +115,12 @@ export function WarnOnUnmatchedProviderVoice(effectiveConfig, driverClass, surfa
  */
 export class RealtimeClientSessionService {
     constructor() {
+        /** Maps session id -> (wireName -> MJActionEntityExtended) built during tool projection. */
+        this.sessionWireActionMaps = new Map();
+        /** Maps targetAgentID -> (wireName -> MJActionEntityExtended) fallback built during tool projection. */
+        this.targetWireActionMaps = new Map();
+        /** Maps session id -> direct actions config resolved during session prep. */
+        this.sessionDirectConfigs = new Map();
         /**
          * IN-FLIGHT DELEGATION REGISTRY — the server half of the client-direct CANCEL channel.
          *
@@ -125,6 +159,33 @@ export class RealtimeClientSessionService {
             ttlMs: 4 * 60 * 60 * 1000, // 4h backstop — generous vs. any realistic session duration
         });
     }
+    /**
+     * Builds a wire-name to action map from candidate actions, sanitizing each
+     * action's name and deduplicating collisions (first action wins).
+     *
+     * @param actions The action entities to index by wire name.
+     * @returns Map of wire-name to action entity.
+     */
+    buildWireActionMap(actions) {
+        const map = new Map();
+        const seen = new Map();
+        for (const action of actions) {
+            if (!action.Name) {
+                continue;
+            }
+            const wireName = SanitizeWireToolName(action.Name);
+            const lower = wireName.toLowerCase();
+            const existing = seen.get(lower);
+            if (existing) {
+                // Colliding action name after sanitization — first action wins, log collision
+                LogError(`RealtimeClientSessionService.buildWireActionMap: wire name collision for '${wireName}' between action '${existing.Name}' and action '${action.Name}'. Keeping '${existing.Name}' (first wins).`);
+                continue;
+            }
+            seen.set(lower, action);
+            map.set(wireName, action);
+        }
+        return map;
+    }
     /**
      * The seeded name of the `MJ: AI Prompts` row whose `TemplateText` carries the first-person
      * progress-narration instructions (with a `{{ progressMessage }}` placeholder). Resolved at
@@ -253,6 +314,7 @@ export class RealtimeClientSessionService {
                     ParentRunID: obs?.CoAgentRunID,
                     TargetAgentID: input.TargetAgentID,
                     AllowedAgents: prep.EffectiveConfig?.realtime?.allowedAgents,
+                    DirectActions: prep.EffectiveConfig?.realtime?.directActions,
                     Call: call,
                 }, contextUser, provider);
                 await session.SendToolResult(call.CallID, result.ResultJson);
@@ -920,6 +982,7 @@ export class RealtimeClientSessionService {
      */
     async configureEngine(contextUser, provider) {
         await AIEngine.Instance.Config(false, contextUser, provider);
+        await ActionEngineServer.Instance.Config(false, contextUser);
     }
     /**
      * Resolves the co-agent from either the supplied entity or its id (from cached metadata).
@@ -1178,7 +1241,7 @@ export class RealtimeClientSessionService {
     }
     /**
      * Builds the {@link RealtimeSessionParams} for the client-direct session: the companion system
-     * prompt plus the stable, target-independent tool set.
+     * prompt plus the registered realtime tool set.
      *
      * @param input The prepare-session input.
      * @param coAgent The resolved co-agent.
@@ -1192,9 +1255,13 @@ export class RealtimeClientSessionService {
      * @returns The assembled session params.
      */
     async buildSessionParams(input, coAgent, modelApiName, contextUser, provider, effectiveConfig, driverClass, modelID, modelVendorID) {
-        const systemPrompt = await this.buildCompanionSystemPrompt(input, coAgent, contextUser, provider, effectiveConfig);
+        const directTools = this.buildDirectActionTools(input.TargetAgentID, effectiveConfig, driverClass, input.AgentSessionID);
+        const systemPrompt = await this.buildCompanionSystemPrompt(input, coAgent, contextUser, provider, effectiveConfig, directTools.length > 0);
         const memoryContext = await this.assembleMemoryContext(input, coAgent, contextUser, provider);
-        const tools = this.buildStableToolSet(input.ExtraTools);
+        const combinedExtra = directTools.length > 0
+            ? [...(input.ExtraTools ?? []), ...directTools]
+            : input.ExtraTools;
+        const tools = this.buildStableToolSet(combinedExtra);
         // Hoisted (rather than built inline at the return) so the mint log below can report the voice
         // that ACTUALLY reached the driver — see the `voice=` field. Same bag, built once.
         const configBag = this.buildSessionConfigBag(input, effectiveConfig, driverClass, modelID, modelVendorID);
@@ -1218,6 +1285,7 @@ export class RealtimeClientSessionService {
             // bound the provider session/token apply min(default, this); the janitor enforces it
             // regardless of driver support via the session deadline stamped by the transport layer.
             MaxSessionSeconds: input.MaxSessionSeconds,
+            UserID: contextUser?.ID,
         };
     }
     /**
@@ -1277,7 +1345,7 @@ export class RealtimeClientSessionService {
      * @param effectiveConfig The resolved effective configuration (voice persona source).
      * @returns The concatenated system prompt (never empty — the framing is always present).
      */
-    async buildCompanionSystemPrompt(input, coAgent, contextUser, provider, effectiveConfig) {
+    async buildCompanionSystemPrompt(input, coAgent, contextUser, provider, effectiveConfig, hasDirectTools = false) {
         const target = this.resolveTargetAgent(input.TargetAgentID);
         const targetName = target?.Name ?? 'the configured target agent';
         // Identity framing comes from the ONE shared producer (see BuildRealtimeAgentFraming) so the agent
@@ -1285,7 +1353,7 @@ export class RealtimeClientSessionService {
         // browser/whiteboard); bridges pass none. Colleagues come from the effective allowed-agent union
         // (Move 4) so the lead knows who it can delegate to and how to narrate each handoff.
         const colleagues = this.buildColleaguesFromConfig(effectiveConfig, input.TargetAgentID);
-        const framing = BuildRealtimeAgentFraming(targetName, this.buildInteractiveSurfaceFraming(input.ExtraTools), colleagues);
+        const framing = BuildRealtimeAgentFraming(targetName, this.buildInteractiveSurfaceFraming(input.ExtraTools), colleagues, hasDirectTools);
         const meetingFraming = this.buildMeetingFraming(input);
         const coAgentPrompt = this.getCoAgentSystemPromptText(coAgent);
         const voiceManner = BuildVoiceMannerSection(effectiveConfig);
@@ -1580,19 +1648,17 @@ export class RealtimeClientSessionService {
         }
     }
     /**
-     * Builds the stable, target-independent tool set every voice session exposes: the single
-     * `invoke-target-agent` tool plus any caller-supplied extra tools. The target is a runtime
-     * argument *inside* the call, never a per-target tool — this keeps the provider contract
-     * identical across targets.
+     * Builds the tool set every voice session exposes: the core `invoke-target-agent` tool plus
+     * any caller-supplied extra tools or projected direct actions. The target is a runtime
+     * argument *inside* the delegation call, keeping the provider delegation contract identical.
      *
-     * @param extraTools Optional additional target-independent tools.
+     * @param extraTools Optional additional tools to register.
      * @returns The tools to register at session start.
      */
     buildStableToolSet(extraTools) {
         const invokeTarget = {
             Name: INVOKE_TARGET_AGENT_TOOL_NAME,
-            Description: 'Hand the user\'s request to the target agent to perform the actual work. Call this whenever ' +
-                'real work (data lookup, analysis, actions) is required, then narrate progress while it runs.',
+            Description: INVOKE_TARGET_AGENT_DESCRIPTION,
             ParametersSchema: {
                 type: 'object',
                 properties: {
@@ -1609,11 +1675,22 @@ export class RealtimeClientSessionService {
                 required: ['request']
             }
         };
-        return extraTools && extraTools.length > 0 ? [invokeTarget, ...extraTools] : [invokeTarget];
+        const result = [invokeTarget];
+        const seenNames = new Set([INVOKE_TARGET_AGENT_TOOL_NAME.toLowerCase()]);
+        if (extraTools && extraTools.length > 0) {
+            for (const tool of extraTools) {
+                const key = tool.Name.toLowerCase();
+                if (!seenNames.has(key)) {
+                    seenNames.add(key);
+                    result.push(tool);
+                }
+            }
+        }
+        return result;
     }
     /**
      * Builds the {@link RealtimeToolBroker} for a relayed tool call, wiring `DelegateToTarget` to a
-     * target-agent run and `ExecuteTool` to a structured "not available" placeholder.
+     * target-agent run and `ExecuteTool` to direct-action execution or a structured "not available" placeholder.
      *
      * @param input The relayed tool input.
      * @param contextUser The calling user.
@@ -1623,7 +1700,7 @@ export class RealtimeClientSessionService {
     buildToolBroker(input, contextUser, provider) {
         const deps = {
             DelegateToTarget: (request) => this.delegateToTarget(input, request, contextUser, provider),
-            ExecuteTool: (call) => this.executeNonTargetTool(call)
+            ExecuteTool: (call) => this.executeNonTargetTool(call, input, contextUser)
         };
         return new RealtimeToolBroker(deps);
     }
@@ -1885,19 +1962,239 @@ export class RealtimeClientSessionService {
         return (await run.Load(parentRunID)) ? run : null;
     }
     /**
-     * Routes a non-target tool call. For now this returns a structured "not available" result —
-     * the richer client/UI/action routing is wired in a later phase. Documented minimal seam.
+     * Inspects whether the resolved realtime driver class supports dynamic tool registration.
+     * Dynamic tool sets (e.g. per-agent direct action projection) are registered on the provider
+     * socket only when the driver explicitly declares `SupportsDynamicToolSet === true`.
      *
-     * @param call The non-target tool call.
-     * @returns A failed {@link ToolExecutionResult} the model can narrate.
+     * @param driverClass The vendor's DriverClass (the ClassFactory key).
+     * @returns True if the driver supports dynamic tool sets, false otherwise.
      */
-    async executeNonTargetTool(call) {
+    driverSupportsDynamicToolSet(driverClass) {
+        if (!driverClass) {
+            return false;
+        }
+        const reg = MJGlobal.Instance.ClassFactory.GetRegistration(BaseRealtimeModel, driverClass);
+        const subClass = reg?.SubClass;
+        return subClass?.SupportsDynamicToolSet === true;
+    }
+    /**
+     * Resolves the active database actions assigned to the target agent.
+     * **Overridable seam** for tests to provide mock action sets without an engine cache.
+     *
+     * @param targetAgentID The target agent ID.
+     * @returns The active action entities assigned to the agent.
+     */
+    getTargetAgentActions(targetAgentID) {
+        const agentActions = (AIEngine.Instance.AgentActions ?? []).filter(aa => UUIDsEqual(aa.AgentID, targetAgentID) && aa.Status === 'Active');
+        return (ActionEngineServer.Instance.Actions ?? []).filter(a => agentActions.some(aa => UUIDsEqual(aa.ActionID, a.ID)) && a.Status === 'Active');
+    }
+    /**
+     * Builds the projected direct action tool definitions for a target agent if supported by the driver.
+     * Gated by driver capability (`SupportsDynamicToolSet`) and explicit configuration opt-in
+     * (`Configuration.realtime.directActions.enabled = true`).
+     *
+     * @param targetAgentID The target agent ID being voiced.
+     * @param effectiveConfig The resolved effective configuration.
+     * @param driverClass The resolved vendor's DriverClass.
+     * @returns The array of projected direct action tools (empty if unsupported or disabled).
+     */
+    buildDirectActionTools(targetAgentID, effectiveConfig, driverClass, agentSessionID) {
+        if (!targetAgentID || !this.driverSupportsDynamicToolSet(driverClass)) {
+            return [];
+        }
+        const directConfig = GetDirectActionsConfig(effectiveConfig);
+        if (!directConfig || !directConfig.enabled) {
+            return [];
+        }
+        const candidateActions = this.getTargetAgentActions(targetAgentID);
+        const allowedActions = candidateActions.filter(action => IsActionAllowedForDirectInvocation(action.Name, directConfig));
+        const wireMap = this.buildWireActionMap(allowedActions);
+        if (agentSessionID) {
+            this.sessionWireActionMaps.set(agentSessionID, wireMap);
+            if (directConfig) {
+                this.sessionDirectConfigs.set(agentSessionID, directConfig);
+            }
+        }
+        this.targetWireActionMaps.set(targetAgentID, wireMap);
+        const tools = [];
+        for (const [wireName, action] of wireMap.entries()) {
+            tools.push(this.mapActionToToolDefinition(action, wireName));
+        }
+        return tools;
+    }
+    /**
+     * Maps an action entity and its metadata parameters to a RealtimeToolDefinition.
+     *
+     * @param action The action entity to map.
+     * @param wireName Optional pre-sanitized wire name. If omitted, derives via {@link SanitizeWireToolName}.
+     * @returns The constructed tool definition.
+     */
+    mapActionToToolDefinition(action, wireName) {
+        const rawParams = (action.Params?.Items && action.Params.Items.length > 0)
+            ? action.Params.Items
+            : (ActionEngineServer.Instance.ActionParams ?? []).filter(p => UUIDsEqual(p.ActionID, action.ID));
+        const inputParams = rawParams.filter(p => {
+            const dir = (p.Type ?? 'Input').trim().toLowerCase();
+            return dir === 'input' || dir === 'both';
+        });
+        const properties = {};
+        const required = [];
+        for (const p of inputParams) {
+            let schemaType = 'string';
+            if (p.IsArray) {
+                schemaType = 'array';
+            }
+            else if (p.ValueType === 'Simple Object' || p.ValueType === 'BaseEntity Sub-Class') {
+                schemaType = 'object';
+            }
+            const propSchema = {
+                type: schemaType,
+                description: p.Description || p.Name
+            };
+            properties[p.Name] = propSchema;
+            if (p.IsRequired) {
+                required.push(p.Name);
+            }
+        }
+        const parametersSchema = {
+            type: 'object',
+            properties: properties,
+            ...(required.length > 0 ? { required } : {})
+        };
         return {
-            CallID: call.CallID,
-            Success: false,
-            Output: `Tool '${call.ToolName}' is not available in this voice session.`
+            Name: wireName ?? SanitizeWireToolName(action.Name),
+            Description: action.Description || `Execute the ${action.Name} action.`,
+            ParametersSchema: parametersSchema
         };
     }
+    /**
+     * Routes a non-target tool call by resolving the action through the wire map, checking the
+     * direct-actions allowlist, and executing via `ActionEngineServer.Instance.RunAction` under a
+     * configured timeout. If the tool is unrecognized, disallowed, or target resolution fails,
+     * returns a structured "not available" result.
+     *
+     * @param call The non-target tool call.
+     * @param input The optional relayed tool input context.
+     * @param contextUser The calling user context.
+     * @returns A {@link ToolExecutionResult} for the model's tool_response.
+     */
+    async executeNonTargetTool(call, input, contextUser) {
+        if (!input?.TargetAgentID) {
+            return {
+                CallID: call.CallID,
+                Success: false,
+                Output: `Tool '${call.ToolName}' is not available in this voice session.`
+            };
+        }
+        const target = this.resolveTargetAgent(input.TargetAgentID);
+        if (!target) {
+            return {
+                CallID: call.CallID,
+                Success: false,
+                Output: `Target agent is not available to execute '${call.ToolName}'.`
+            };
+        }
+        const candidateActions = this.getTargetAgentActions(target.ID);
+        const candidateWireMap = this.buildWireActionMap(candidateActions);
+        const action = (input?.AgentSessionID ? this.sessionWireActionMaps.get(input.AgentSessionID)?.get(call.ToolName) : undefined)
+            ?? candidateWireMap.get(call.ToolName)
+            ?? Array.from(candidateWireMap.entries()).find(([w]) => w.toLowerCase() === call.ToolName.trim().toLowerCase())?.[1];
+        if (!action) {
+            return {
+                CallID: call.CallID,
+                Success: false,
+                Output: `Tool '${call.ToolName}' is not available to this agent.`
+            };
+        }
+        const directConfig = input?.DirectActions
+            ?? (input?.AgentSessionID ? this.sessionDirectConfigs.get(input.AgentSessionID) : undefined)
+            ?? GetDirectActionsConfig(this.resolveEffectiveConfig(target, undefined, target));
+        if (!IsActionAllowedForDirectInvocation(action.Name, directConfig)) {
+            return {
+                CallID: call.CallID,
+                Success: false,
+                Output: `Action '${action.Name}' is not enabled for direct voice invocation.`
+            };
+        }
+        if (!contextUser) {
+            return {
+                CallID: call.CallID,
+                Success: false,
+                Output: `Execution of action '${action.Name}' refused: authenticated user context is required.`
+            };
+        }
+        const timeoutMs = directConfig?.timeoutMs ?? 10_000;
+        const executingUser = contextUser;
+        try {
+            const rawParams = this.parseActionParams(call.Arguments);
+            const actionParams = Object.entries(rawParams).map(([name, value]) => ({
+                Name: name,
+                Value: value,
+                Type: 'Input'
+            }));
+            const runParams = new RunActionParams();
+            runParams.Action = action;
+            runParams.ContextUser = executingUser;
+            runParams.Params = actionParams;
+            runParams.Filters = [];
+            let timerHandle;
+            const timeoutPromise = new Promise((_, reject) => {
+                timerHandle = setTimeout(() => {
+                    reject(new Error(`Action '${action.Name}' execution timed out after ${timeoutMs}ms`));
+                }, timeoutMs);
+                if (typeof timerHandle.unref === 'function') {
+                    timerHandle.unref();
+                }
+            });
+            const result = await Promise.race([
+                ActionEngineServer.Instance.RunAction(runParams),
+                timeoutPromise
+            ]).finally(() => {
+                if (timerHandle) {
+                    clearTimeout(timerHandle);
+                }
+            });
+            const outputText = result.Message || (result.Success ? 'Action completed successfully.' : 'Action failed.');
+            return {
+                CallID: call.CallID,
+                Success: result.Success,
+                Output: outputText
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                CallID: call.CallID,
+                Success: false,
+                Output: `Action '${action.Name}' failed: ${message}`
+            };
+        }
+    }
+    /**
+     * Parses JSON arguments string into a key-value record of parameters.
+     * Distinguishes "no arguments" (valid for zero-param action) from "unparseable JSON".
+     *
+     * @param argumentsJson The raw arguments string emitted by the model.
+     * @returns The parsed arguments record.
+     * @throws ToolArgumentsError with actionable message when arguments are present but unparseable.
+     */
+    parseActionParams(argumentsJson) {
+        if (!argumentsJson || argumentsJson.trim() === '') {
+            return {};
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(argumentsJson);
+        }
+        catch (err) {
+            const syntaxMsg = err instanceof Error ? err.message : String(err);
+            throw new ToolArgumentsError(`Unparseable JSON arguments: ${syntaxMsg}. Please provide valid JSON formatted arguments.`);
+        }
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            return parsed;
+        }
+        throw new ToolArgumentsError(`Tool arguments must be a JSON object, but received ${Array.isArray(parsed) ? 'an array' : typeof parsed}. Please format arguments as a JSON object.`);
+    }
     /**
      * Parses the natural-language request text out of an `invoke-target-agent` call's arguments.
      * Falls back to the raw argument string when it is not the expected `{ request: string }` JSON.