@memberjunction/server 5.43.0 → 5.45.0

package/src/resolvers/RingCentralTelephonyResolver.ts

@@ -0,0 +1,64 @@
+/**
+ * @fileoverview GraphQL surface for OUTBOUND RingCentral telephony: `PlaceRingCentralCall` rings a real
+ * phone from an agent identity and connects the pinned agent. Thin — it authorizes the caller, then
+ * delegates to the startup-constructed {@link RingCentralTelephonyService} (which owns the bridge
+ * orchestration + the shared media registry). Inbound calls arrive via the public
+ * `POST /telephony/ringcentral/webhook` notification, not GraphQL.
+ *
+ * @module @memberjunction/server
+ */
+
+import { Resolver, Mutation, Arg, Ctx, ObjectType, Field } from 'type-graphql';
+import { LogError, IMetadataProvider } from '@memberjunction/core';
+import { AppContext } from '../types.js';
+import { ResolverBase } from '../generic/ResolverBase.js';
+import { GetReadWriteProvider } from '../util.js';
+import { GetRingCentralTelephonyService } from '../telephony/ringcentral-runtime.js';
+
+/** Result of an outbound RingCentral place-call attempt. */
+@ObjectType()
+export class PlaceRingCentralCallResult {
+    @Field(() => Boolean)
+    Success: boolean;
+
+    @Field(() => String, { nullable: true })
+    ErrorMessage?: string;
+
+    /** The placed RingCentral telephony session id (the bridge's external connection id). */
+    @Field(() => String)
+    SessionId: string;
+}
+
+@Resolver()
+export class RingCentralTelephonyResolver extends ResolverBase {
+    /**
+     * Places an outbound call from the given agent identity (its phone number is the caller-id) to a
+     * destination number, connecting the pinned agent over the realtime bridge. Returns the telephony
+     * session id.
+     */
+    @Mutation(() => PlaceRingCentralCallResult)
+    async PlaceRingCentralCall(
+        @Arg('agentIdentityId', () => String) agentIdentityId: string,
+        @Arg('toNumber', () => String) toNumber: string,
+        @Ctx() context: AppContext = {} as AppContext,
+    ): Promise<PlaceRingCentralCallResult> {
+        const failure = (msg: string): PlaceRingCentralCallResult => ({ Success: false, ErrorMessage: msg, SessionId: '' });
+        try {
+            const user = this.GetUserFromPayload(context.userPayload);
+            if (!user) {
+                return failure('Unable to determine current user.');
+            }
+            const service = GetRingCentralTelephonyService();
+            if (!service) {
+                return failure('RingCentral telephony is not configured on this server.');
+            }
+            const provider = GetReadWriteProvider(context.providers) as unknown as IMetadataProvider;
+            const sessionId = await service.PlaceOutboundCall(agentIdentityId, toNumber, user, provider);
+            return { Success: true, SessionId: sessionId };
+        } catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            LogError(`PlaceRingCentralCall failed: ${msg}`);
+            return failure(msg);
+        }
+    }
+}

package/src/resolvers/RunAIAgentResolver.ts

@@ -12,6 +12,7 @@ import { PUSH_STATUS_UPDATES_TOPIC } from '../generic/PushStatusResolver.js';
 import { startLivenessPulse } from '../generic/FireAndForgetHeartbeat.js';
 import { RequireSystemUser } from '../directives/RequireSystemUser.js';
 import { GetReadWriteProvider } from '../util.js';
+import { resolveWidgetGuestRunContext, elevateUserPayload } from '../realtimeWidget/widgetGuestElevation.js';
 import { SafeJSONParse, UUIDsEqual } from '@memberjunction/global';
 import { GetAttachmentService } from '@memberjunction/aiengine';
 import { NotificationEngine } from '@memberjunction/notifications';
@@ -376,7 +377,12 @@ export class RunAIAgentResolver extends ResolverBase {
         conversationId?: string,
         /** Optional external ref the caller can read to observe the agent run as it becomes available
          *  (used by the fire-and-forget liveness pulse to enrich heartbeats with the run id/status). */
-        runRef?: { current: MJAIAgentRunEntityExtended | null }
+        runRef?: { current: MJAIAgentRunEntityExtended | null },
+        /** Per-request Plan Mode toggle — threaded into ExecuteAgentParams.planMode (root-agent HITL gate). */
+        planMode?: boolean,
+        /** Skill IDs the user requested (via `/skill-name`) — threaded into ExecuteAgentParams.requestedSkillIDs.
+         *  The framework intersects them with the agent's accepted skills AND the user's Run permission. */
+        requestedSkillIDs?: string[]
     ): Promise<AIAgentRunResult> {
         const startTime = Date.now();
         
@@ -428,6 +434,8 @@ export class RunAIAgentResolver extends ResolverBase {
                 lastRunId: lastRunId,
                 autoPopulateLastRunPayload: autoPopulateLastRunPayload,
                 configurationId: configurationId,
+                planMode: planMode,
+                requestedSkillIDs: requestedSkillIDs,
                 data: parsedData,
                 context: {
                     dataSource: dataSource
@@ -614,7 +622,12 @@ export class RunAIAgentResolver extends ResolverBase {
         @Arg('createNotification', { nullable: true }) createNotification?: boolean,
         @Arg('sourceArtifactId', { nullable: true }) sourceArtifactId?: string,
         @Arg('sourceArtifactVersionId', { nullable: true }) sourceArtifactVersionId?: string,
-        @Arg('fireAndForget', { nullable: true }) fireAndForget?: boolean
+        @Arg('fireAndForget', { nullable: true }) fireAndForget?: boolean,
+        /** Per-request Plan Mode toggle — symmetric with RunAIAgentFromConversationDetail. */
+        @Arg('planMode', { nullable: true }) planMode?: boolean,
+        /** Skill IDs the user requested — symmetric with RunAIAgentFromConversationDetail. Intersected
+         *  server-side with the agent's accepted skills AND the user's Run permission. */
+        @Arg('requestedSkillIDs', () => [String], { nullable: true }) requestedSkillIDs?: string[]
     ): Promise<AIAgentRunResult> {
         // Check API key scope authorization for agent execution
         await this.CheckAPIKeyScopeAuthorization('agent:execute', agentId, userPayload);
@@ -628,7 +641,7 @@ export class RunAIAgentResolver extends ResolverBase {
                 p, dataSource, agentId, userPayload, messagesJson, sessionId, pubSub,
                 data, payload, lastRunId, autoPopulateLastRunPayload, configurationId,
                 conversationDetailId, createArtifacts || false, createNotification || false,
-                sourceArtifactId, sourceArtifactVersionId
+                sourceArtifactId, sourceArtifactVersionId, undefined /*conversationId*/, planMode, requestedSkillIDs
             );
 
             LogStatus(`🔥 Fire-and-forget: Agent ${agentId} execution started in background for session ${sessionId}`);
@@ -658,7 +671,11 @@ export class RunAIAgentResolver extends ResolverBase {
             createArtifacts || false,
             createNotification || false,
             sourceArtifactId,
-            sourceArtifactVersionId
+            sourceArtifactVersionId,
+            undefined, // conversationId (not pre-resolved on this path)
+            undefined, // runRef
+            planMode,
+            requestedSkillIDs
         );
     }
 
@@ -684,7 +701,11 @@ export class RunAIAgentResolver extends ResolverBase {
         @Arg('createArtifacts', { nullable: true }) createArtifacts?: boolean,
         @Arg('createNotification', { nullable: true }) createNotification?: boolean,
         @Arg('sourceArtifactId', { nullable: true }) sourceArtifactId?: string,
-        @Arg('sourceArtifactVersionId', { nullable: true }) sourceArtifactVersionId?: string
+        @Arg('sourceArtifactVersionId', { nullable: true }) sourceArtifactVersionId?: string,
+        /** Per-request Plan Mode toggle — symmetric with the other run mutations. */
+        @Arg('planMode', { nullable: true }) planMode?: boolean,
+        /** User-requested skill IDs — symmetric with the other run mutations. */
+        @Arg('requestedSkillIDs', () => [String], { nullable: true }) requestedSkillIDs?: string[]
     ): Promise<AIAgentRunResult> {
         const p = GetReadWriteProvider(providers);
         return this.executeAIAgent(
@@ -705,7 +726,11 @@ export class RunAIAgentResolver extends ResolverBase {
             createArtifacts || false,
             createNotification || false,
             sourceArtifactId,
-            sourceArtifactVersionId
+            sourceArtifactVersionId,
+            undefined, // conversationId (not pre-resolved on this path)
+            undefined, // runRef
+            planMode,
+            requestedSkillIDs
         );
     }
 
@@ -932,7 +957,9 @@ export class RunAIAgentResolver extends ResolverBase {
         @Arg('createNotification', { nullable: true }) createNotification?: boolean,
         @Arg('sourceArtifactId', { nullable: true }) sourceArtifactId?: string,
         @Arg('sourceArtifactVersionId', { nullable: true }) sourceArtifactVersionId?: string,
-        @Arg('fireAndForget', { nullable: true }) fireAndForget?: boolean
+        @Arg('fireAndForget', { nullable: true }) fireAndForget?: boolean,
+        @Arg('planMode', { nullable: true }) planMode?: boolean,
+        @Arg('requestedSkillIDs', () => [String], { nullable: true }) requestedSkillIDs?: string[]
     ): Promise<AIAgentRunResult> {
         // Check API key scope authorization for agent execution
         await this.CheckAPIKeyScopeAuthorization('agent:execute', agentId, userPayload);
@@ -948,6 +975,17 @@ export class RunAIAgentResolver extends ResolverBase {
             };
         }
 
+        // PUBLIC WEB-WIDGET PRIVILEGED DISPATCH (public-web-widget.md Phase 0): when the request is a
+        // widget guest, the agent runs under a TRUSTED SERVER PRINCIPAL and the agent id is taken
+        // AUTHORITATIVELY from the widget instance (never the client-supplied arg) — so a guest needs
+        // no grants to WRITE the AI run entities and cannot run an arbitrary agent under elevation.
+        // Conversation OWNERSHIP is still enforced under the guest principal below: the guest loads its
+        // own ConversationDetail through the Widget Guest RLS filters, so a detail id from another
+        // session resolves to "not found" before any elevated work happens.
+        const widgetElevation = await resolveWidgetGuestRunContext(userPayload, p);
+        const effectiveAgentId = widgetElevation ? widgetElevation.pinnedAgentId : agentId;
+        const effectiveUserPayload = widgetElevation ? elevateUserPayload(userPayload, widgetElevation.elevatedUser) : userPayload;
+
         try {
             // LATENCY OPTIMIZATION (Opt #2 + #3): Load ConversationDetail once here to extract
             // conversationId, then pass it downstream. Previously this record was loaded multiple
@@ -978,13 +1016,13 @@ export class RunAIAgentResolver extends ResolverBase {
                 // Fire-and-forget mode: start execution in background, return immediately.
                 // The client will receive the result via WebSocket PubSub completion event.
                 this.executeAgentInBackground(
-                    p, dataSource, agentId, userPayload, messagesJson, sessionId, pubSub,
+                    p, dataSource, effectiveAgentId, effectiveUserPayload, messagesJson, sessionId, pubSub,
                     data, payload, lastRunId, autoPopulateLastRunPayload, configurationId,
                     conversationDetailId, createArtifacts || false, createNotification || false,
-                    sourceArtifactId, sourceArtifactVersionId, conversationId
+                    sourceArtifactId, sourceArtifactVersionId, conversationId, planMode, requestedSkillIDs
                 );
 
-                LogStatus(`🔥 Fire-and-forget: Agent ${agentId} execution started in background for session ${sessionId}`);
+                LogStatus(`🔥 Fire-and-forget: Agent ${effectiveAgentId} execution started in background for session ${sessionId}`);
 
                 return {
                     success: true,
@@ -996,8 +1034,8 @@ export class RunAIAgentResolver extends ResolverBase {
             return this.executeAIAgent(
                 p,
                 dataSource,
-                agentId,
-                userPayload,
+                effectiveAgentId,
+                effectiveUserPayload,
                 messagesJson,
                 sessionId,
                 pubSub,
@@ -1012,7 +1050,10 @@ export class RunAIAgentResolver extends ResolverBase {
                 createNotification || false,
                 sourceArtifactId,
                 sourceArtifactVersionId,
-                conversationId // LATENCY OPT #2: pass pre-resolved conversationId
+                conversationId, // LATENCY OPT #2: pass pre-resolved conversationId
+                undefined, // runRef
+                planMode,
+                requestedSkillIDs
             );
         } catch (error) {
             const errorMessage = (error as Error).message || 'Unknown error loading conversation history';
@@ -1227,7 +1268,11 @@ export class RunAIAgentResolver extends ResolverBase {
         sourceArtifactId?: string,
         sourceArtifactVersionId?: string,
         /** LATENCY OPT #2: Pre-resolved conversationId avoids redundant DB load in AgentRunner */
-        conversationId?: string
+        conversationId?: string,
+        /** Per-request Plan Mode toggle — threaded through to ExecuteAgentParams.planMode. */
+        planMode?: boolean,
+        /** Skill IDs the user requested — threaded through to ExecuteAgentParams.requestedSkillIDs. */
+        requestedSkillIDs?: string[]
     ): void {
         // Ref the liveness pulse reads to enrich heartbeats once the run is created.
         const runRef: { current: MJAIAgentRunEntityExtended | null } = { current: null };
@@ -1245,7 +1290,7 @@ export class RunAIAgentResolver extends ResolverBase {
             p, dataSource, agentId, userPayload, messagesJson, sessionId, pubSub,
             data, payload, undefined, lastRunId, autoPopulateLastRunPayload,
             configurationId, conversationDetailId, createArtifacts, createNotification,
-            sourceArtifactId, sourceArtifactVersionId, conversationId, runRef
+            sourceArtifactId, sourceArtifactVersionId, conversationId, runRef, planMode, requestedSkillIDs
         ).catch((error: unknown) => {
             // Background execution failed unexpectedly (executeAIAgent has its own try-catch,
             // so this would only fire for truly unexpected errors).

package/src/resolvers/SearchKnowledgeResolver.ts

@@ -213,6 +213,7 @@ export class SearchKnowledgeResolver extends ResolverBase {
     ): Promise<SearchKnowledgeResult> {
         const startTime = Date.now();
         try {
+            await this.CheckAPIKeyScopeAuthorization('search:execute', '*', userPayload);
             const currentUser = this.GetUserFromPayload(userPayload);
             if (!currentUser) {
                 return this.errorResult('Unable to determine current user', startTime);
@@ -400,6 +401,7 @@ export class SearchKnowledgeResolver extends ResolverBase {
     ): Promise<SearchKnowledgeResult> {
         const startTime = Date.now();
         try {
+            await this.CheckAPIKeyScopeAuthorization('search:execute', '*', userPayload);
             const currentUser = this.GetUserFromPayload(userPayload);
             if (!currentUser) {
                 return this.errorResult('Unable to determine current user', startTime);

package/src/resolvers/TeamsMeetingsResolver.ts

@@ -0,0 +1,68 @@
+/**
+ * @fileoverview GraphQL surface for Teams meeting joins: `StartTeamsMeetingSession` has an agent identity
+ * join a Teams meeting by URL and connects the pinned agent over the realtime bridge. Thin — it authorizes
+ * the caller, then delegates to the startup-constructed {@link TeamsMeetingsService} (which owns the bridge
+ * orchestration + the shared ACS media registry). Roster/call-ended updates arrive via the public
+ * `POST /meetings/teams/notifications` Graph webhook, not GraphQL.
+ *
+ * Mirrors `TelephonyResolver.ts` (the Twilio `PlaceTwilioCall` equivalent).
+ *
+ * @module @memberjunction/server
+ */
+
+import { Resolver, Mutation, Arg, Ctx, ObjectType, Field } from 'type-graphql';
+import { LogError, IMetadataProvider } from '@memberjunction/core';
+import { AppContext } from '../types.js';
+import { ResolverBase } from '../generic/ResolverBase.js';
+import { GetReadWriteProvider } from '../util.js';
+import { GetTeamsMeetingsService } from '../telephony/teams-meetings-runtime.js';
+
+/** Result of a Teams meeting join attempt. */
+@ObjectType()
+export class StartTeamsMeetingResult {
+    @Field(() => Boolean)
+    Success: boolean;
+
+    @Field(() => String, { nullable: true })
+    ErrorMessage?: string;
+
+    /** The Graph call id the bot joined (the bridge's external connection id), when successful. */
+    @Field(() => String)
+    CallId: string;
+}
+
+@Resolver()
+export class TeamsMeetingsResolver extends ResolverBase {
+    /**
+     * Has the given agent identity join a Teams meeting by URL, connecting the pinned agent over the realtime
+     * bridge. Returns the Graph call id.
+     */
+    @Mutation(() => StartTeamsMeetingResult)
+    async StartTeamsMeetingSession(
+        @Arg('agentIdentityId', () => String) agentIdentityId: string,
+        @Arg('joinUrl', () => String) joinUrl: string,
+        @Ctx() context: AppContext = {} as AppContext,
+    ): Promise<StartTeamsMeetingResult> {
+        const failure = (msg: string): StartTeamsMeetingResult => ({ Success: false, ErrorMessage: msg, CallId: '' });
+        try {
+            const user = this.GetUserFromPayload(context.userPayload);
+            if (!user) {
+                return failure('Unable to determine current user.');
+            }
+            const service = GetTeamsMeetingsService();
+            if (!service) {
+                return failure('Teams meetings are not configured on this server.');
+            }
+            const provider = GetReadWriteProvider(context.providers) as unknown as IMetadataProvider;
+            const result = await service.JoinMeetingByUrl(agentIdentityId, joinUrl, user, provider);
+            if (!result.accepted) {
+                return failure(result.reason ?? 'The meeting join was not accepted.');
+            }
+            return { Success: true, CallId: result.callId ?? '' };
+        } catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            LogError(`StartTeamsMeetingSession failed: ${msg}`);
+            return failure(msg);
+        }
+    }
+}

package/src/resolvers/TelephonyResolver.ts

@@ -0,0 +1,63 @@
+/**
+ * @fileoverview GraphQL surface for OUTBOUND telephony: `PlaceTwilioCall` rings a real phone from
+ * an agent identity and connects the pinned agent. Thin — it authorizes the caller, then delegates to
+ * the startup-constructed {@link TwilioTelephonyService} (which owns the bridge orchestration + the
+ * shared media registry). Inbound calls arrive via the public `POST /telephony/twilio/voice` webhook,
+ * not GraphQL.
+ *
+ * @module @memberjunction/server
+ */
+
+import { Resolver, Mutation, Arg, Ctx, ObjectType, Field } from 'type-graphql';
+import { LogError, IMetadataProvider } from '@memberjunction/core';
+import { AppContext } from '../types.js';
+import { ResolverBase } from '../generic/ResolverBase.js';
+import { GetReadWriteProvider } from '../util.js';
+import { GetTwilioTelephonyService } from '../telephony/telephony-runtime.js';
+
+/** Result of an outbound place-call attempt. */
+@ObjectType()
+export class PlaceCallResult {
+    @Field(() => Boolean)
+    Success: boolean;
+
+    @Field(() => String, { nullable: true })
+    ErrorMessage?: string;
+
+    /** The placed Twilio Call SID (the bridge's external connection id). */
+    @Field(() => String)
+    CallSid: string;
+}
+
+@Resolver()
+export class TelephonyResolver extends ResolverBase {
+    /**
+     * Places an outbound call from the given agent identity (its phone number is the caller-id) to a
+     * destination number, connecting the pinned agent over the realtime bridge. Returns the Call SID.
+     */
+    @Mutation(() => PlaceCallResult)
+    async PlaceTwilioCall(
+        @Arg('agentIdentityId', () => String) agentIdentityId: string,
+        @Arg('toNumber', () => String) toNumber: string,
+        @Ctx() context: AppContext = {} as AppContext,
+    ): Promise<PlaceCallResult> {
+        const failure = (msg: string): PlaceCallResult => ({ Success: false, ErrorMessage: msg, CallSid: '' });
+        try {
+            const user = this.GetUserFromPayload(context.userPayload);
+            if (!user) {
+                return failure('Unable to determine current user.');
+            }
+            const service = GetTwilioTelephonyService();
+            if (!service) {
+                return failure('Twilio telephony is not configured on this server.');
+            }
+            const provider = GetReadWriteProvider(context.providers) as unknown as IMetadataProvider;
+            const callSid = await service.PlaceOutboundCall(agentIdentityId, toNumber, user, provider);
+            return { Success: true, CallSid: callSid };
+        } catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            LogError(`PlaceTwilioCall failed: ${msg}`);
+            return failure(msg);
+        }
+    }
+}

package/src/resolvers/TestQuerySQLResolver.ts

@@ -2,7 +2,6 @@ import { Arg, Ctx, Field, InputType, Int, ObjectType, Query, Resolver } from 'ty
 import { GraphQLJSONObject } from 'graphql-type-json';
 import { RunQuery, IRunQueryProvider, LogError, LogStatus, QueryExecutionSpec } from '@memberjunction/core';
 import { AppContext } from '../types.js';
-import { RequireSystemUser } from '../directives/RequireSystemUser.js';
 import { GetReadOnlyProvider } from '../util.js';
 import { ResolverBase } from '../generic/ResolverBase.js';
 
@@ -85,7 +84,7 @@ export class TestQuerySQLResult {
  * enabling external systems (e.g., Skip-Brain) to test query SQL before saving to the database.
  *
  * Security:
- * - Requires system user authentication (@RequireSystemUser)
+ * - Requires `query:test` scope for API key users (no-op for JWT auth)
  * - Uses read-only database connection (no mutation possible)
  * - Enforces MaxRows limit (default 100) to prevent unbounded queries
  *
@@ -93,7 +92,6 @@ export class TestQuerySQLResult {
  */
 @Resolver()
 export class TestQuerySQLResolver extends ResolverBase {
-    @RequireSystemUser()
     @Query(() => TestQuerySQLResult, {
         description: 'Test transient SQL with full composition + Nunjucks template processing without requiring a saved query'
     })
@@ -102,6 +100,7 @@ export class TestQuerySQLResolver extends ResolverBase {
         @Ctx() context: AppContext
     ): Promise<TestQuerySQLResult> {
         try {
+            await this.CheckAPIKeyScopeAuthorization('query:test', '*', context.userPayload);
             // Use read-only provider for security — no mutation possible
             const provider = GetReadOnlyProvider(context.providers, { allowFallbackToReadWrite: false });
             if (!provider) {

package/src/resolvers/VonageTelephonyResolver.ts

@@ -0,0 +1,63 @@
+/**
+ * @fileoverview GraphQL surface for OUTBOUND Vonage telephony: `PlaceVonageCall` rings a real phone from
+ * an agent identity and connects the pinned agent. Thin — it authorizes the caller, then delegates to
+ * the startup-constructed {@link VonageTelephonyService} (which owns the bridge orchestration + the
+ * shared media registry). Inbound calls arrive via the public `POST /telephony/vonage/answer` webhook,
+ * not GraphQL.
+ *
+ * @module @memberjunction/server
+ */
+
+import { Resolver, Mutation, Arg, Ctx, ObjectType, Field } from 'type-graphql';
+import { LogError, IMetadataProvider } from '@memberjunction/core';
+import { AppContext } from '../types.js';
+import { ResolverBase } from '../generic/ResolverBase.js';
+import { GetReadWriteProvider } from '../util.js';
+import { GetVonageTelephonyService } from '../telephony/vonage-runtime.js';
+
+/** Result of an outbound place-call attempt. */
+@ObjectType()
+export class PlaceVonageCallResult {
+    @Field(() => Boolean)
+    Success: boolean;
+
+    @Field(() => String, { nullable: true })
+    ErrorMessage?: string;
+
+    /** The placed Vonage call UUID (the bridge's external connection id). */
+    @Field(() => String)
+    CallId: string;
+}
+
+@Resolver()
+export class VonageTelephonyResolver extends ResolverBase {
+    /**
+     * Places an outbound call from the given agent identity (its phone number is the caller-id) to a
+     * destination number, connecting the pinned agent over the realtime bridge. Returns the call UUID.
+     */
+    @Mutation(() => PlaceVonageCallResult)
+    async PlaceVonageCall(
+        @Arg('agentIdentityId', () => String) agentIdentityId: string,
+        @Arg('toNumber', () => String) toNumber: string,
+        @Ctx() context: AppContext = {} as AppContext,
+    ): Promise<PlaceVonageCallResult> {
+        const failure = (msg: string): PlaceVonageCallResult => ({ Success: false, ErrorMessage: msg, CallId: '' });
+        try {
+            const user = this.GetUserFromPayload(context.userPayload);
+            if (!user) {
+                return failure('Unable to determine current user.');
+            }
+            const service = GetVonageTelephonyService();
+            if (!service) {
+                return failure('Vonage telephony is not configured on this server.');
+            }
+            const provider = GetReadWriteProvider(context.providers) as unknown as IMetadataProvider;
+            const callId = await service.PlaceOutboundCall(agentIdentityId, toNumber, user, provider);
+            return { Success: true, CallId: callId };
+        } catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            LogError(`PlaceVonageCall failed: ${msg}`);
+            return failure(msg);
+        }
+    }
+}