@signalwire/sdk 2.0.0 → 2.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +1 -1
- package/src/AgentBase.ts +113 -4
- package/src/AgentServer.ts +31 -4
- package/src/ContextBuilder.ts +33 -2
- package/src/DataMap.ts +30 -2
- package/src/FunctionResult.ts +40 -3
- package/src/PomBuilder.ts +29 -1
- package/src/SWMLService.ts +38 -6
- package/src/ServerlessAdapter.ts +20 -1
- package/src/SwmlBuilder.ts +26 -1
- package/src/TypeInference.ts +27 -9
- package/src/WebService.ts +27 -5
- package/src/index.ts +73 -7
- package/src/livewire/index.ts +343 -41
- package/src/prefabs/ConciergeAgent.ts +22 -0
- package/src/prefabs/FAQBotAgent.ts +32 -1
- package/src/prefabs/InfoGathererAgent.ts +41 -1
- package/src/prefabs/ReceptionistAgent.ts +30 -1
- package/src/prefabs/SurveyAgent.ts +26 -1
- package/src/relay/Action.ts +174 -6
- package/src/relay/Call.ts +459 -43
- package/src/relay/Deferred.ts +27 -4
- package/src/relay/Message.ts +54 -3
- package/src/relay/RelayClient.ts +167 -18
- package/src/relay/RelayError.ts +7 -1
- package/src/relay/RelayEvent.ts +52 -0
- package/src/rest/HttpClient.ts +61 -0
- package/src/rest/RestError.ts +14 -0
- package/src/rest/base/BaseResource.ts +16 -3
- package/src/rest/base/CrudResource.ts +52 -5
- package/src/rest/base/CrudWithAddresses.ts +12 -1
- package/src/rest/index.ts +30 -0
- package/src/rest/namespaces/addresses.ts +33 -1
- package/src/rest/namespaces/calling.ts +348 -1
- package/src/rest/namespaces/chat.ts +13 -2
- package/src/rest/namespaces/compat.ts +469 -9
- package/src/rest/namespaces/datasphere.ts +48 -5
- package/src/rest/namespaces/fabric.ts +197 -2
- package/src/rest/namespaces/imported-numbers.ts +13 -2
- package/src/rest/namespaces/logs.ts +68 -1
- package/src/rest/namespaces/lookup.ts +19 -2
- package/src/rest/namespaces/mfa.ts +35 -4
- package/src/rest/namespaces/number-groups.ts +35 -5
- package/src/rest/namespaces/phone-numbers.ts +35 -3
- package/src/rest/namespaces/project.ts +30 -1
- package/src/rest/namespaces/pubsub.ts +13 -2
- package/src/rest/namespaces/queues.ts +29 -4
- package/src/rest/namespaces/recordings.ts +26 -1
- package/src/rest/namespaces/registry.ts +100 -1
- package/src/rest/namespaces/short-codes.ts +27 -1
- package/src/rest/namespaces/sip-profile.ts +18 -3
- package/src/rest/namespaces/verified-callers.ts +22 -3
- package/src/rest/namespaces/video.ts +168 -1
- package/src/rest/pagination.ts +22 -8
- package/src/skills/SkillBase.ts +37 -2
- package/src/skills/SkillManager.ts +8 -4
- package/src/skills/builtin/api_ninjas_trivia.ts +5 -0
- package/src/skills/builtin/ask_claude.ts +5 -0
- package/src/skills/builtin/claude_skills.ts +5 -0
- package/src/skills/builtin/custom_skills.ts +15 -0
- package/src/skills/builtin/datasphere.ts +9 -0
- package/src/skills/builtin/datasphere_serverless.ts +8 -0
- package/src/skills/builtin/datetime.ts +7 -0
- package/src/skills/builtin/google_maps.ts +5 -0
- package/src/skills/builtin/info_gatherer.ts +10 -0
- package/src/skills/builtin/joke.ts +5 -0
- package/src/skills/builtin/math.ts +7 -0
- package/src/skills/builtin/mcp_gateway.ts +8 -0
- package/src/skills/builtin/native_vector_search.ts +9 -0
- package/src/skills/builtin/play_background_file.ts +9 -0
- package/src/skills/builtin/spider.ts +5 -0
- package/src/skills/builtin/swml_transfer.ts +10 -0
- package/src/skills/builtin/weather_api.ts +7 -0
- package/src/skills/builtin/web_search.ts +9 -0
- package/src/skills/builtin/wikipedia_search.ts +5 -0
|
@@ -17,10 +17,26 @@ export class VideoRooms extends CrudResource {
|
|
|
17
17
|
super(http, basePath);
|
|
18
18
|
}
|
|
19
19
|
|
|
20
|
+
/**
|
|
21
|
+
* List outbound streams associated with a room.
|
|
22
|
+
*
|
|
23
|
+
* @param roomId - Unique identifier of the video room.
|
|
24
|
+
* @param params - Optional filter / pagination query parameters.
|
|
25
|
+
* @returns A paginated list of outbound streams.
|
|
26
|
+
* @throws {RestError} On any non-2xx HTTP response.
|
|
27
|
+
*/
|
|
20
28
|
async listStreams(roomId: string, params?: QueryParams): Promise<any> {
|
|
21
29
|
return this._http.get(this._path(roomId, 'streams'), params);
|
|
22
30
|
}
|
|
23
31
|
|
|
32
|
+
/**
|
|
33
|
+
* Start a new outbound stream from a room (e.g. RTMP to YouTube, Twitch).
|
|
34
|
+
*
|
|
35
|
+
* @param roomId - Unique identifier of the video room.
|
|
36
|
+
* @param body - Stream configuration (destination URL, credentials, etc.).
|
|
37
|
+
* @returns The newly-created stream record.
|
|
38
|
+
* @throws {RestError} On any non-2xx HTTP response.
|
|
39
|
+
*/
|
|
24
40
|
async createStream(roomId: string, body: any): Promise<any> {
|
|
25
41
|
return this._http.post(this._path(roomId, 'streams'), body);
|
|
26
42
|
}
|
|
@@ -32,6 +48,13 @@ export class VideoRoomTokens extends BaseResource {
|
|
|
32
48
|
super(http, basePath);
|
|
33
49
|
}
|
|
34
50
|
|
|
51
|
+
/**
|
|
52
|
+
* Issue a JWT token that grants a browser / mobile client access to a room.
|
|
53
|
+
*
|
|
54
|
+
* @param body - Token payload (`room_name`, `user_name`, `permissions`, etc.).
|
|
55
|
+
* @returns The token record, typically `{ token: "eyJ..." }`.
|
|
56
|
+
* @throws {RestError} On any non-2xx HTTP response.
|
|
57
|
+
*/
|
|
35
58
|
async create(body: any): Promise<any> {
|
|
36
59
|
return this._http.post(this._basePath, body);
|
|
37
60
|
}
|
|
@@ -43,22 +66,60 @@ export class VideoRoomSessions extends BaseResource {
|
|
|
43
66
|
super(http, basePath);
|
|
44
67
|
}
|
|
45
68
|
|
|
69
|
+
/**
|
|
70
|
+
* List past and active room sessions in the project.
|
|
71
|
+
*
|
|
72
|
+
* @param params - Optional filter / pagination query parameters.
|
|
73
|
+
* @returns A paginated list of room sessions.
|
|
74
|
+
* @throws {RestError} On any non-2xx HTTP response.
|
|
75
|
+
*/
|
|
46
76
|
async list(params?: QueryParams): Promise<any> {
|
|
47
77
|
return this._http.get(this._basePath, params);
|
|
48
78
|
}
|
|
49
79
|
|
|
80
|
+
/**
|
|
81
|
+
* Fetch a single room session by ID.
|
|
82
|
+
*
|
|
83
|
+
* @param sessionId - Unique identifier of the room session.
|
|
84
|
+
* @returns The room-session record.
|
|
85
|
+
* @throws {RestError} On any non-2xx HTTP response (including `404`).
|
|
86
|
+
*/
|
|
50
87
|
async get(sessionId: string): Promise<any> {
|
|
51
88
|
return this._http.get(this._path(sessionId));
|
|
52
89
|
}
|
|
53
90
|
|
|
91
|
+
/**
|
|
92
|
+
* List the event log for a room session.
|
|
93
|
+
*
|
|
94
|
+
* @param sessionId - Unique identifier of the room session.
|
|
95
|
+
* @param params - Optional filter / pagination query parameters.
|
|
96
|
+
* @returns A paginated list of session events.
|
|
97
|
+
* @throws {RestError} On any non-2xx HTTP response.
|
|
98
|
+
*/
|
|
54
99
|
async listEvents(sessionId: string, params?: QueryParams): Promise<any> {
|
|
55
100
|
return this._http.get(this._path(sessionId, 'events'), params);
|
|
56
101
|
}
|
|
57
102
|
|
|
103
|
+
/**
|
|
104
|
+
* List members that participated in a room session.
|
|
105
|
+
*
|
|
106
|
+
* @param sessionId - Unique identifier of the room session.
|
|
107
|
+
* @param params - Optional filter / pagination query parameters.
|
|
108
|
+
* @returns A paginated list of members (past and current).
|
|
109
|
+
* @throws {RestError} On any non-2xx HTTP response.
|
|
110
|
+
*/
|
|
58
111
|
async listMembers(sessionId: string, params?: QueryParams): Promise<any> {
|
|
59
112
|
return this._http.get(this._path(sessionId, 'members'), params);
|
|
60
113
|
}
|
|
61
114
|
|
|
115
|
+
/**
|
|
116
|
+
* List recordings captured during a room session.
|
|
117
|
+
*
|
|
118
|
+
* @param sessionId - Unique identifier of the room session.
|
|
119
|
+
* @param params - Optional filter / pagination query parameters.
|
|
120
|
+
* @returns A paginated list of session recordings.
|
|
121
|
+
* @throws {RestError} On any non-2xx HTTP response.
|
|
122
|
+
*/
|
|
62
123
|
async listRecordings(sessionId: string, params?: QueryParams): Promise<any> {
|
|
63
124
|
return this._http.get(this._path(sessionId, 'recordings'), params);
|
|
64
125
|
}
|
|
@@ -70,18 +131,47 @@ export class VideoRoomRecordings extends BaseResource {
|
|
|
70
131
|
super(http, basePath);
|
|
71
132
|
}
|
|
72
133
|
|
|
134
|
+
/**
|
|
135
|
+
* List all room recordings in the project.
|
|
136
|
+
*
|
|
137
|
+
* @param params - Optional filter / pagination query parameters.
|
|
138
|
+
* @returns A paginated list of recordings.
|
|
139
|
+
* @throws {RestError} On any non-2xx HTTP response.
|
|
140
|
+
*/
|
|
73
141
|
async list(params?: QueryParams): Promise<any> {
|
|
74
142
|
return this._http.get(this._basePath, params);
|
|
75
143
|
}
|
|
76
144
|
|
|
145
|
+
/**
|
|
146
|
+
* Fetch a room recording by ID.
|
|
147
|
+
*
|
|
148
|
+
* @param recordingId - Unique identifier of the recording.
|
|
149
|
+
* @returns The recording record.
|
|
150
|
+
* @throws {RestError} On any non-2xx HTTP response (including `404`).
|
|
151
|
+
*/
|
|
77
152
|
async get(recordingId: string): Promise<any> {
|
|
78
153
|
return this._http.get(this._path(recordingId));
|
|
79
154
|
}
|
|
80
155
|
|
|
156
|
+
/**
|
|
157
|
+
* Delete a room recording.
|
|
158
|
+
*
|
|
159
|
+
* @param recordingId - Unique identifier of the recording.
|
|
160
|
+
* @returns The platform's delete response.
|
|
161
|
+
* @throws {RestError} On any non-2xx HTTP response.
|
|
162
|
+
*/
|
|
81
163
|
async delete(recordingId: string): Promise<any> {
|
|
82
164
|
return this._http.delete(this._path(recordingId));
|
|
83
165
|
}
|
|
84
166
|
|
|
167
|
+
/**
|
|
168
|
+
* List event log entries for a room recording.
|
|
169
|
+
*
|
|
170
|
+
* @param recordingId - Unique identifier of the recording.
|
|
171
|
+
* @param params - Optional filter / pagination query parameters.
|
|
172
|
+
* @returns A paginated list of recording events.
|
|
173
|
+
* @throws {RestError} On any non-2xx HTTP response.
|
|
174
|
+
*/
|
|
85
175
|
async listEvents(recordingId: string, params?: QueryParams): Promise<any> {
|
|
86
176
|
return this._http.get(this._path(recordingId, 'events'), params);
|
|
87
177
|
}
|
|
@@ -95,14 +185,38 @@ export class VideoConferences extends CrudResource {
|
|
|
95
185
|
super(http, basePath);
|
|
96
186
|
}
|
|
97
187
|
|
|
188
|
+
/**
|
|
189
|
+
* List conference tokens associated with a conference.
|
|
190
|
+
*
|
|
191
|
+
* @param conferenceId - Unique identifier of the conference.
|
|
192
|
+
* @param params - Optional filter / pagination query parameters.
|
|
193
|
+
* @returns A paginated list of conference tokens.
|
|
194
|
+
* @throws {RestError} On any non-2xx HTTP response.
|
|
195
|
+
*/
|
|
98
196
|
async listConferenceTokens(conferenceId: string, params?: QueryParams): Promise<any> {
|
|
99
197
|
return this._http.get(this._path(conferenceId, 'conference_tokens'), params);
|
|
100
198
|
}
|
|
101
199
|
|
|
200
|
+
/**
|
|
201
|
+
* List outbound streams associated with a conference.
|
|
202
|
+
*
|
|
203
|
+
* @param conferenceId - Unique identifier of the conference.
|
|
204
|
+
* @param params - Optional filter / pagination query parameters.
|
|
205
|
+
* @returns A paginated list of streams.
|
|
206
|
+
* @throws {RestError} On any non-2xx HTTP response.
|
|
207
|
+
*/
|
|
102
208
|
async listStreams(conferenceId: string, params?: QueryParams): Promise<any> {
|
|
103
209
|
return this._http.get(this._path(conferenceId, 'streams'), params);
|
|
104
210
|
}
|
|
105
211
|
|
|
212
|
+
/**
|
|
213
|
+
* Start an outbound stream from a conference (e.g. RTMP to YouTube).
|
|
214
|
+
*
|
|
215
|
+
* @param conferenceId - Unique identifier of the conference.
|
|
216
|
+
* @param body - Stream configuration (destination URL, credentials, etc.).
|
|
217
|
+
* @returns The newly-created stream record.
|
|
218
|
+
* @throws {RestError} On any non-2xx HTTP response.
|
|
219
|
+
*/
|
|
106
220
|
async createStream(conferenceId: string, body: any): Promise<any> {
|
|
107
221
|
return this._http.post(this._path(conferenceId, 'streams'), body);
|
|
108
222
|
}
|
|
@@ -114,10 +228,24 @@ export class VideoConferenceTokens extends BaseResource {
|
|
|
114
228
|
super(http, basePath);
|
|
115
229
|
}
|
|
116
230
|
|
|
231
|
+
/**
|
|
232
|
+
* Fetch a conference token by ID.
|
|
233
|
+
*
|
|
234
|
+
* @param tokenId - Unique identifier of the conference token.
|
|
235
|
+
* @returns The conference-token record.
|
|
236
|
+
* @throws {RestError} On any non-2xx HTTP response (including `404`).
|
|
237
|
+
*/
|
|
117
238
|
async get(tokenId: string): Promise<any> {
|
|
118
239
|
return this._http.get(this._path(tokenId));
|
|
119
240
|
}
|
|
120
241
|
|
|
242
|
+
/**
|
|
243
|
+
* Reset / regenerate a conference token, invalidating the previous value.
|
|
244
|
+
*
|
|
245
|
+
* @param tokenId - Unique identifier of the conference token to reset.
|
|
246
|
+
* @returns The refreshed token record with a new secret.
|
|
247
|
+
* @throws {RestError} On any non-2xx HTTP response.
|
|
248
|
+
*/
|
|
121
249
|
async reset(tokenId: string): Promise<any> {
|
|
122
250
|
return this._http.post(this._path(tokenId, 'reset'));
|
|
123
251
|
}
|
|
@@ -129,27 +257,66 @@ export class VideoStreams extends BaseResource {
|
|
|
129
257
|
super(http, basePath);
|
|
130
258
|
}
|
|
131
259
|
|
|
260
|
+
/**
|
|
261
|
+
* Fetch a video stream by ID.
|
|
262
|
+
*
|
|
263
|
+
* @param streamId - Unique identifier of the stream.
|
|
264
|
+
* @returns The stream record.
|
|
265
|
+
* @throws {RestError} On any non-2xx HTTP response (including `404`).
|
|
266
|
+
*/
|
|
132
267
|
async get(streamId: string): Promise<any> {
|
|
133
268
|
return this._http.get(this._path(streamId));
|
|
134
269
|
}
|
|
135
270
|
|
|
271
|
+
/**
|
|
272
|
+
* Update a video stream's configuration (e.g. destination URL).
|
|
273
|
+
*
|
|
274
|
+
* @param streamId - Unique identifier of the stream.
|
|
275
|
+
* @param body - Full updated stream attributes (replace semantics).
|
|
276
|
+
* @returns The updated stream record.
|
|
277
|
+
* @throws {RestError} On any non-2xx HTTP response.
|
|
278
|
+
*/
|
|
136
279
|
async update(streamId: string, body: any): Promise<any> {
|
|
137
280
|
return this._http.put(this._path(streamId), body);
|
|
138
281
|
}
|
|
139
282
|
|
|
283
|
+
/**
|
|
284
|
+
* Stop and delete a video stream.
|
|
285
|
+
*
|
|
286
|
+
* @param streamId - Unique identifier of the stream.
|
|
287
|
+
* @returns The platform's delete response.
|
|
288
|
+
* @throws {RestError} On any non-2xx HTTP response.
|
|
289
|
+
*/
|
|
140
290
|
async delete(streamId: string): Promise<any> {
|
|
141
291
|
return this._http.delete(this._path(streamId));
|
|
142
292
|
}
|
|
143
293
|
}
|
|
144
294
|
|
|
145
|
-
/**
|
|
295
|
+
/**
|
|
296
|
+
* Video API namespace.
|
|
297
|
+
*
|
|
298
|
+
* Access via `client.video.*`.
|
|
299
|
+
*
|
|
300
|
+
* @example Create a room and issue a client token
|
|
301
|
+
* ```ts
|
|
302
|
+
* const room = await client.video.rooms.create({ name: 'standup' });
|
|
303
|
+
* const token = await client.video.roomTokens.create({ room_name: 'standup', user_name: 'Alice' });
|
|
304
|
+
* ```
|
|
305
|
+
*/
|
|
146
306
|
export class VideoNamespace {
|
|
307
|
+
/** Video room CRUD plus outbound stream management. */
|
|
147
308
|
readonly rooms: VideoRooms;
|
|
309
|
+
/** Issue JWT tokens for browser / mobile clients to join rooms. */
|
|
148
310
|
readonly roomTokens: VideoRoomTokens;
|
|
311
|
+
/** Past and active room session read access. */
|
|
149
312
|
readonly roomSessions: VideoRoomSessions;
|
|
313
|
+
/** Room recording read, delete, and event-log access. */
|
|
150
314
|
readonly roomRecordings: VideoRoomRecordings;
|
|
315
|
+
/** Video conference CRUD plus stream / token management. */
|
|
151
316
|
readonly conferences: VideoConferences;
|
|
317
|
+
/** Individual conference token read / reset operations. */
|
|
152
318
|
readonly conferenceTokens: VideoConferenceTokens;
|
|
319
|
+
/** Individual video stream read / update / delete operations. */
|
|
153
320
|
readonly streams: VideoStreams;
|
|
154
321
|
|
|
155
322
|
constructor(http: HttpClient) {
|
package/src/rest/pagination.ts
CHANGED
|
@@ -12,10 +12,17 @@ import type { QueryParams } from './types.js';
|
|
|
12
12
|
/**
|
|
13
13
|
* Async generator that yields items across paginated API responses.
|
|
14
14
|
*
|
|
15
|
-
*
|
|
16
|
-
*
|
|
17
|
-
*
|
|
18
|
-
* @
|
|
15
|
+
* Handles both relay REST (`links.next`) and LAML (`next_page_uri`) pagination
|
|
16
|
+
* styles transparently.
|
|
17
|
+
*
|
|
18
|
+
* @typeParam T - Element type yielded.
|
|
19
|
+
* @param http - {@link HttpClient} instance used to fetch each page.
|
|
20
|
+
* @param path - Initial API path (absolute URL or path relative to `http.baseUrl`).
|
|
21
|
+
* @param params - Query parameters applied to the first request only.
|
|
22
|
+
* Subsequent pages use the server-supplied next-page URL unchanged.
|
|
23
|
+
* @param dataKey - Key on each response containing the array of items.
|
|
24
|
+
* Defaults to `"data"`.
|
|
25
|
+
* @returns An async iterable that yields one `T` per call until exhausted.
|
|
19
26
|
*/
|
|
20
27
|
export async function* paginate<T>(
|
|
21
28
|
http: HttpClient,
|
|
@@ -65,10 +72,17 @@ export async function* paginate<T>(
|
|
|
65
72
|
/**
|
|
66
73
|
* Collect all paginated items into an array.
|
|
67
74
|
*
|
|
68
|
-
* @
|
|
69
|
-
*
|
|
70
|
-
*
|
|
71
|
-
*
|
|
75
|
+
* Convenience wrapper around {@link paginate} for callers who want the full
|
|
76
|
+
* list. Beware: loads every page into memory — for very large result sets,
|
|
77
|
+
* iterate via `paginate()` directly.
|
|
78
|
+
*
|
|
79
|
+
* @typeParam T - Element type collected.
|
|
80
|
+
* @param http - {@link HttpClient} instance used to fetch each page.
|
|
81
|
+
* @param path - Initial API path.
|
|
82
|
+
* @param params - Query parameters applied to the first request.
|
|
83
|
+
* @param dataKey - Key on each response containing the array of items.
|
|
84
|
+
* Defaults to `"data"`.
|
|
85
|
+
* @returns A flat array of every item across all pages.
|
|
72
86
|
*/
|
|
73
87
|
export async function paginateAll<T>(
|
|
74
88
|
http: HttpClient,
|
package/src/skills/SkillBase.ts
CHANGED
|
@@ -84,8 +84,43 @@ export interface ParameterSchemaEntry {
|
|
|
84
84
|
/**
|
|
85
85
|
* Abstract base class for agent skills.
|
|
86
86
|
*
|
|
87
|
-
* Skills are modular capabilities that
|
|
88
|
-
*
|
|
87
|
+
* Skills are modular, reusable capabilities that plug into an {@link AgentBase}.
|
|
88
|
+
* A single skill can contribute:
|
|
89
|
+
*
|
|
90
|
+
* - **Tools** (SWAIG functions) via `getTools()` or `defineTool()`
|
|
91
|
+
* - **Prompt sections** via `_getPromptSections()`
|
|
92
|
+
* - **Speech hints** via `getHints()`
|
|
93
|
+
* - **Global data** seeded into each call via `getGlobalData()`
|
|
94
|
+
*
|
|
95
|
+
* Skills are added to an agent with `agent.addSkill('name', config)` and the
|
|
96
|
+
* {@link SkillManager} calls `setAgent()` + `setup()` in sequence before the
|
|
97
|
+
* agent starts serving requests.
|
|
98
|
+
*
|
|
99
|
+
* @example Custom skill
|
|
100
|
+
* ```ts
|
|
101
|
+
* import { SkillBase, FunctionResult, type SkillToolDefinition } from '@signalwire/sdk';
|
|
102
|
+
*
|
|
103
|
+
* export class GreetingSkill extends SkillBase {
|
|
104
|
+
* static override SKILL_NAME = 'greeting';
|
|
105
|
+
* static override SKILL_DESCRIPTION = 'Responds with a configurable greeting.';
|
|
106
|
+
*
|
|
107
|
+
* override getTools(): SkillToolDefinition[] {
|
|
108
|
+
* return [{
|
|
109
|
+
* name: 'say_hello',
|
|
110
|
+
* description: 'Say a friendly hello.',
|
|
111
|
+
* parameters: { type: 'object', properties: {} },
|
|
112
|
+
* handler: () => new FunctionResult(this.getConfig('message', 'Hi!')),
|
|
113
|
+
* }];
|
|
114
|
+
* }
|
|
115
|
+
* }
|
|
116
|
+
*
|
|
117
|
+
* // In your agent:
|
|
118
|
+
* agent.addSkill(new GreetingSkill({ message: 'Howdy!' }));
|
|
119
|
+
* ```
|
|
120
|
+
*
|
|
121
|
+
* @see {@link SkillManager}
|
|
122
|
+
* @see {@link SkillRegistry}
|
|
123
|
+
* @see {@link AgentBase.addSkill}
|
|
89
124
|
*/
|
|
90
125
|
export abstract class SkillBase {
|
|
91
126
|
/**
|
|
@@ -60,12 +60,16 @@ export class SkillManager {
|
|
|
60
60
|
* Add a skill to the manager, validating env vars and calling setup().
|
|
61
61
|
* Uses the skill's instance key for deduplication.
|
|
62
62
|
*
|
|
63
|
-
*
|
|
64
|
-
*
|
|
65
|
-
*
|
|
66
|
-
* contract (`skill_manager.py` lines 114-118).
|
|
63
|
+
* {@link loadSkill} / {@link loadSkillByName} wrap this and catch to return
|
|
64
|
+
* `[false, msg]`, matching Python `load_skill`'s return contract
|
|
65
|
+
* (`skill_manager.py` lines 114-118).
|
|
67
66
|
*
|
|
68
67
|
* @param skill - The skill instance to add.
|
|
68
|
+
* @returns Resolves once the skill is registered.
|
|
69
|
+
* @throws {Error} When a single-instance skill is already loaded, its
|
|
70
|
+
* required environment variables are missing, its parameter schema is
|
|
71
|
+
* empty, its required packages cannot be imported, or `setup()` returns
|
|
72
|
+
* `false`.
|
|
69
73
|
*/
|
|
70
74
|
async addSkill(skill: SkillBase): Promise<void> {
|
|
71
75
|
const name = skill.skillName;
|
|
@@ -50,6 +50,11 @@ const VALID_CATEGORIES = [
|
|
|
50
50
|
*
|
|
51
51
|
* Tier 2 built-in skill. Requires the `API_NINJAS_KEY` environment variable.
|
|
52
52
|
* Supports optional `default_category` and `reveal_answer` config options.
|
|
53
|
+
*
|
|
54
|
+
* @example
|
|
55
|
+
* ```ts
|
|
56
|
+
* agent.addSkill('api_ninjas_trivia', { default_category: 'sciencenature' });
|
|
57
|
+
* ```
|
|
53
58
|
*/
|
|
54
59
|
export class ApiNinjasTriviaSkill extends SkillBase {
|
|
55
60
|
static override SKILL_NAME = 'api_ninjas_trivia';
|
|
@@ -72,6 +72,11 @@ interface AnthropicErrorResponse {
|
|
|
72
72
|
* Tier 3 built-in skill. Requires the `ANTHROPIC_API_KEY` environment variable.
|
|
73
73
|
* Supports `model` and `max_tokens` config options to control which Claude model
|
|
74
74
|
* is used and the maximum response length.
|
|
75
|
+
*
|
|
76
|
+
* @example
|
|
77
|
+
* ```ts
|
|
78
|
+
* agent.addSkill('ask_claude', { model: 'claude-sonnet-4-6', max_tokens: 512 });
|
|
79
|
+
* ```
|
|
75
80
|
*/
|
|
76
81
|
export class AskClaudeSkill extends SkillBase {
|
|
77
82
|
// TS-only skill (no Python equivalent).
|
|
@@ -72,6 +72,11 @@ interface ParsedSkill {
|
|
|
72
72
|
* This skill parses Claude Code skill directories and makes them available
|
|
73
73
|
* as SWAIG tools that the AI can call. Each Claude skill becomes a tool
|
|
74
74
|
* that returns the skill's instructions when invoked.
|
|
75
|
+
*
|
|
76
|
+
* @example
|
|
77
|
+
* ```ts
|
|
78
|
+
* agent.addSkill('claude_skills', { skills_dir: './claude-skills' });
|
|
79
|
+
* ```
|
|
75
80
|
*/
|
|
76
81
|
export class ClaudeSkillsSkill extends SkillBase {
|
|
77
82
|
// Python ground truth: skills/claude_skills/skill.py
|
|
@@ -75,6 +75,21 @@ interface CustomSkillsConfigData {
|
|
|
75
75
|
* **Security warning:** This skill uses `new Function()` to compile user-provided
|
|
76
76
|
* code at runtime. It is gated behind the `SWML_ALLOW_CUSTOM_HANDLER_CODE=true`
|
|
77
77
|
* environment variable to prevent unintended code execution.
|
|
78
|
+
*
|
|
79
|
+
* @example
|
|
80
|
+
* ```ts
|
|
81
|
+
* // Requires SWML_ALLOW_CUSTOM_HANDLER_CODE=true
|
|
82
|
+
* agent.addSkill('custom_skills', {
|
|
83
|
+
* tools: [
|
|
84
|
+
* {
|
|
85
|
+
* name: 'echo',
|
|
86
|
+
* description: 'Echo back the caller-supplied message.',
|
|
87
|
+
* parameters: { type: 'object', properties: { msg: { type: 'string' } } },
|
|
88
|
+
* handlerBody: 'return new FunctionResult(args.msg);',
|
|
89
|
+
* },
|
|
90
|
+
* ],
|
|
91
|
+
* });
|
|
92
|
+
* ```
|
|
78
93
|
*/
|
|
79
94
|
export class CustomSkillsSkill extends SkillBase {
|
|
80
95
|
// TS-only skill (no Python equivalent).
|
|
@@ -58,6 +58,15 @@ interface DataSphereResponse {
|
|
|
58
58
|
* `SIGNALWIRE_PROJECT_ID`, `SIGNALWIRE_TOKEN`, and `SIGNALWIRE_SPACE` environment
|
|
59
59
|
* variables. Supports `count`, `distance`, `tags`, `language`, `pos_to_expand`,
|
|
60
60
|
* `max_synonyms`, and `no_results_message` config options.
|
|
61
|
+
*
|
|
62
|
+
* @example
|
|
63
|
+
* ```ts
|
|
64
|
+
* agent.addSkill('datasphere', {
|
|
65
|
+
* document_id: 'doc_abc123',
|
|
66
|
+
* count: 3,
|
|
67
|
+
* tags: ['faq'],
|
|
68
|
+
* });
|
|
69
|
+
* ```
|
|
61
70
|
*/
|
|
62
71
|
export class DataSphereSkill extends SkillBase {
|
|
63
72
|
// Python ground truth: skills/datasphere/skill.py:20-27.
|
|
@@ -33,6 +33,14 @@ const DEFAULT_NO_RESULTS_MESSAGE =
|
|
|
33
33
|
* executes directly, without a webhook endpoint. Supports `document_id`,
|
|
34
34
|
* `count`, `distance`, `tags`, `language`, `pos_to_expand`, `max_synonyms`,
|
|
35
35
|
* and `no_results_message` config options.
|
|
36
|
+
*
|
|
37
|
+
* @example
|
|
38
|
+
* ```ts
|
|
39
|
+
* agent.addSkill('datasphere_serverless', {
|
|
40
|
+
* document_id: 'doc_abc123',
|
|
41
|
+
* count: 3,
|
|
42
|
+
* });
|
|
43
|
+
* ```
|
|
36
44
|
*/
|
|
37
45
|
export class DataSphereServerlessSkill extends SkillBase {
|
|
38
46
|
// Python ground truth: skills/datasphere_serverless/skill.py:20-28
|
|
@@ -18,6 +18,13 @@ import { FunctionResult } from '../../FunctionResult.js';
|
|
|
18
18
|
*
|
|
19
19
|
* Tier 1 built-in skill with no external dependencies. Supports all IANA
|
|
20
20
|
* timezone identifiers via the Intl.DateTimeFormat API.
|
|
21
|
+
*
|
|
22
|
+
* Registers two SWAIG tools: `get_current_time` and `get_current_date`.
|
|
23
|
+
*
|
|
24
|
+
* @example
|
|
25
|
+
* ```ts
|
|
26
|
+
* agent.addSkill('datetime');
|
|
27
|
+
* ```
|
|
21
28
|
*/
|
|
22
29
|
export class DateTimeSkill extends SkillBase {
|
|
23
30
|
// Python ground truth: skills/datetime/skill.py
|
|
@@ -98,6 +98,11 @@ interface RoutesV2Response {
|
|
|
98
98
|
*
|
|
99
99
|
* Tier 3 built-in skill. Requires the `GOOGLE_MAPS_API_KEY` environment variable.
|
|
100
100
|
* Supports a `default_mode` config option ("driving"|"walking"|"bicycling"|"transit").
|
|
101
|
+
*
|
|
102
|
+
* @example
|
|
103
|
+
* ```ts
|
|
104
|
+
* agent.addSkill('google_maps', { default_mode: 'driving' });
|
|
105
|
+
* ```
|
|
101
106
|
*/
|
|
102
107
|
export class GoogleMapsSkill extends SkillBase {
|
|
103
108
|
// Python ground truth: skills/google_maps/skill.py
|
|
@@ -46,6 +46,16 @@ interface QuestionDefinition {
|
|
|
46
46
|
* `questions` config, the same `prefix` / `completion_message` options,
|
|
47
47
|
* the same two tools (`start_questions`, `submit_answer`), and the same
|
|
48
48
|
* state shape in `global_data`.
|
|
49
|
+
*
|
|
50
|
+
* @example
|
|
51
|
+
* ```ts
|
|
52
|
+
* agent.addSkill('info_gatherer', {
|
|
53
|
+
* questions: [
|
|
54
|
+
* { key_name: 'name', question_text: 'What is your name?' },
|
|
55
|
+
* { key_name: 'email', question_text: 'Your email?', confirm: true },
|
|
56
|
+
* ],
|
|
57
|
+
* });
|
|
58
|
+
* ```
|
|
49
59
|
*/
|
|
50
60
|
export class InfoGathererSkill extends SkillBase {
|
|
51
61
|
// Python ground truth: skills/info_gatherer/skill.py:26-31
|
|
@@ -87,6 +87,11 @@ const VALID_CATEGORIES = ['general', 'programming', 'dad'];
|
|
|
87
87
|
*
|
|
88
88
|
* Tier 1 built-in skill with no external dependencies. Includes general,
|
|
89
89
|
* programming, and dad joke categories.
|
|
90
|
+
*
|
|
91
|
+
* @example
|
|
92
|
+
* ```ts
|
|
93
|
+
* agent.addSkill('joke');
|
|
94
|
+
* ```
|
|
90
95
|
*/
|
|
91
96
|
export class JokeSkill extends SkillBase {
|
|
92
97
|
// Python ground truth: skills/joke/skill.py
|
|
@@ -64,6 +64,13 @@ function safeEvaluate(expr: string): number {
|
|
|
64
64
|
*
|
|
65
65
|
* Tier 1 built-in skill with no external dependencies. Only allows digits,
|
|
66
66
|
* basic arithmetic operators, parentheses, decimal points, and spaces.
|
|
67
|
+
*
|
|
68
|
+
* Registers a single SWAIG tool: `calculate`.
|
|
69
|
+
*
|
|
70
|
+
* @example
|
|
71
|
+
* ```ts
|
|
72
|
+
* agent.addSkill('math');
|
|
73
|
+
* ```
|
|
67
74
|
*/
|
|
68
75
|
export class MathSkill extends SkillBase {
|
|
69
76
|
// Python ground truth: skills/math/skill.py
|
|
@@ -49,6 +49,14 @@ interface McpToolDefinition {
|
|
|
49
49
|
* services, enumerates each service's tools, and registers them as SWAIG
|
|
50
50
|
* tools prefixed with `tool_prefix` (default `mcp_`). A hidden hangup hook
|
|
51
51
|
* tool cleans up MCP sessions when the call ends.
|
|
52
|
+
*
|
|
53
|
+
* @example
|
|
54
|
+
* ```ts
|
|
55
|
+
* agent.addSkill('mcp_gateway', {
|
|
56
|
+
* gateway_url: 'https://mcp-gateway.example.com',
|
|
57
|
+
* tool_prefix: 'mcp_',
|
|
58
|
+
* });
|
|
59
|
+
* ```
|
|
52
60
|
*/
|
|
53
61
|
export class McpGatewaySkill extends SkillBase {
|
|
54
62
|
// Python ground truth: skills/mcp_gateway/skill.py:~70-76
|
|
@@ -146,6 +146,15 @@ function scoreTfIdf(
|
|
|
146
146
|
* Document search using TF-IDF in-memory scoring or a remote search server.
|
|
147
147
|
*
|
|
148
148
|
* Multi-instance capable (distinguished by `tool_name` + `index_file`).
|
|
149
|
+
*
|
|
150
|
+
* @example Local JSON index
|
|
151
|
+
* ```ts
|
|
152
|
+
* agent.addSkill('native_vector_search', {
|
|
153
|
+
* tool_name: 'search_docs',
|
|
154
|
+
* index_file: './data/support-docs.json',
|
|
155
|
+
* count: 3,
|
|
156
|
+
* });
|
|
157
|
+
* ```
|
|
149
158
|
*/
|
|
150
159
|
export class NativeVectorSearchSkill extends SkillBase {
|
|
151
160
|
// Python ground truth: skills/native_vector_search/skill.py:~75-82
|
|
@@ -39,6 +39,15 @@ interface PreConfiguredFile {
|
|
|
39
39
|
* values that trigger the corresponding file playback.
|
|
40
40
|
* - Free-form `default_file_url` / `allowed_domains`: emits two tools,
|
|
41
41
|
* `play_background` (arbitrary URL) and `stop_background`.
|
|
42
|
+
*
|
|
43
|
+
* @example
|
|
44
|
+
* ```ts
|
|
45
|
+
* agent.addSkill('play_background_file', {
|
|
46
|
+
* files: [
|
|
47
|
+
* { key: 'hold', url: 'https://cdn.example.com/hold-music.mp3', description: 'Hold music' },
|
|
48
|
+
* ],
|
|
49
|
+
* });
|
|
50
|
+
* ```
|
|
42
51
|
*/
|
|
43
52
|
export class PlayBackgroundFileSkill extends SkillBase {
|
|
44
53
|
// Python ground truth: skills/play_background_file/skill.py
|
|
@@ -56,6 +56,11 @@ const STRIP_TAG_REGEXES: RegExp[] = [
|
|
|
56
56
|
* mirrors the Python schema (delay, concurrent_requests, timeout, max_pages,
|
|
57
57
|
* max_depth, extract_type, max_text_length, clean_text, selectors,
|
|
58
58
|
* follow_patterns, user_agent, headers, follow_robots_txt, cache_enabled).
|
|
59
|
+
*
|
|
60
|
+
* @example
|
|
61
|
+
* ```ts
|
|
62
|
+
* agent.addSkill('spider', { max_pages: 5, max_depth: 2 });
|
|
63
|
+
* ```
|
|
59
64
|
*/
|
|
60
65
|
export class SpiderSkill extends SkillBase {
|
|
61
66
|
// Python ground truth: skills/spider/skill.py:~140-145
|
|
@@ -59,6 +59,16 @@ interface TransferConfig {
|
|
|
59
59
|
* Multi-instance capable (distinguished by `tool_name`).
|
|
60
60
|
* Accepts either Python-style `transfers` config (regex → per-entry config)
|
|
61
61
|
* or TypeScript-style `patterns` array of named destinations.
|
|
62
|
+
*
|
|
63
|
+
* @example
|
|
64
|
+
* ```ts
|
|
65
|
+
* agent.addSkill('swml_transfer', {
|
|
66
|
+
* patterns: [
|
|
67
|
+
* { name: 'sales', pattern: /sales|pricing|buy/i, to: '+15551112222' },
|
|
68
|
+
* { name: 'support', pattern: /help|support|broken/i, to: '+15553334444' },
|
|
69
|
+
* ],
|
|
70
|
+
* });
|
|
71
|
+
* ```
|
|
62
72
|
*/
|
|
63
73
|
export class SwmlTransferSkill extends SkillBase {
|
|
64
74
|
// Python ground truth: skills/swml_transfer/skill.py:~60-67
|
|
@@ -57,6 +57,13 @@ interface WeatherApiResponse {
|
|
|
57
57
|
* **Unit aliases:** For migration compatibility with the Python SDK the `units`
|
|
58
58
|
* config also accepts `"fahrenheit"` (normalized to `"imperial"`) and
|
|
59
59
|
* `"celsius"` (normalized to `"metric"`).
|
|
60
|
+
*
|
|
61
|
+
* @example
|
|
62
|
+
* ```ts
|
|
63
|
+
* agent.addSkill('weather_api', { units: 'imperial' });
|
|
64
|
+
* // or pass the key explicitly:
|
|
65
|
+
* agent.addSkill('weather_api', { api_key: process.env.WEATHER_API_KEY });
|
|
66
|
+
* ```
|
|
60
67
|
*/
|
|
61
68
|
export class WeatherApiSkill extends SkillBase {
|
|
62
69
|
// Python ground truth: skills/weather_api/skill.py
|
|
@@ -191,6 +191,15 @@ interface GoogleSearchResponse {
|
|
|
191
191
|
* Supported config: `tool_name`, `num_results`, `no_results_message`,
|
|
192
192
|
* `safe_search`, `delay`, `max_content_length`, `oversample_factor`,
|
|
193
193
|
* `min_quality_score`.
|
|
194
|
+
*
|
|
195
|
+
* @example
|
|
196
|
+
* ```ts
|
|
197
|
+
* agent.addSkill('web_search', {
|
|
198
|
+
* api_key: process.env.GOOGLE_SEARCH_API_KEY,
|
|
199
|
+
* search_engine_id: process.env.GOOGLE_CSE_ID,
|
|
200
|
+
* num_results: 3,
|
|
201
|
+
* });
|
|
202
|
+
* ```
|
|
194
203
|
*/
|
|
195
204
|
export class WebSearchSkill extends SkillBase {
|
|
196
205
|
// Python ground truth: skills/web_search/skill.py:559-567
|