@signalwire/sdk 2.0.0

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.
Files changed (325) hide show
  1. package/.github/workflows/publish.yml +27 -0
  2. package/.github/workflows/test.yml +17 -0
  3. package/CLAUDE.md +112 -0
  4. package/README.md +254 -0
  5. package/docs/MIGRATION-2.0.md +81 -0
  6. package/docs/agent-guide.md +869 -0
  7. package/docs/agent_guide.md +1026 -0
  8. package/docs/api-reference.md +2420 -0
  9. package/docs/api_reference.md +1301 -0
  10. package/docs/architecture.md +843 -0
  11. package/docs/cli-guide.md +579 -0
  12. package/docs/cli_guide.md +448 -0
  13. package/docs/cloud_functions_guide.md +474 -0
  14. package/docs/configuration.md +422 -0
  15. package/docs/contexts-guide.md +787 -0
  16. package/docs/contexts_guide.md +511 -0
  17. package/docs/datamap-guide.md +1141 -0
  18. package/docs/datamap_guide.md +595 -0
  19. package/docs/llm_parameters.md +239 -0
  20. package/docs/mcp_gateway_reference.md +648 -0
  21. package/docs/mcp_integration.md +108 -0
  22. package/docs/prefabs-guide.md +800 -0
  23. package/docs/sdk_features.md +477 -0
  24. package/docs/security.md +436 -0
  25. package/docs/serverless-guide.md +513 -0
  26. package/docs/skills-guide.md +857 -0
  27. package/docs/skills-system.md +301 -0
  28. package/docs/skills_parameter_schema.md +392 -0
  29. package/docs/skills_system.md +467 -0
  30. package/docs/swaig-reference.md +1627 -0
  31. package/docs/swaig_reference.md +910 -0
  32. package/docs/swml_service_guide.md +600 -0
  33. package/docs/third_party_skills.md +533 -0
  34. package/docs/web_service.md +677 -0
  35. package/examples/README.md +131 -0
  36. package/examples/advanced-datamap.ts +100 -0
  37. package/examples/advanced-dynamic-config.ts +70 -0
  38. package/examples/auto-vivified.ts +94 -0
  39. package/examples/call-flow.ts +63 -0
  40. package/examples/comprehensive-dynamic.ts +125 -0
  41. package/examples/contexts-steps.ts +65 -0
  42. package/examples/custom-path.ts +45 -0
  43. package/examples/datamap-tools.ts +55 -0
  44. package/examples/datasphere-multi-instance.ts +63 -0
  45. package/examples/datasphere-serverless-env.ts +68 -0
  46. package/examples/datasphere-webhook-env.ts +66 -0
  47. package/examples/datasphere.ts +37 -0
  48. package/examples/declarative.ts +100 -0
  49. package/examples/dynamic-config.ts +54 -0
  50. package/examples/dynamic-info-gatherer.ts +69 -0
  51. package/examples/dynamic-swml-service.ts +67 -0
  52. package/examples/gather-info.ts +71 -0
  53. package/examples/gather-per-question-functions-demo.ts +140 -0
  54. package/examples/joke-agent.ts +34 -0
  55. package/examples/kubernetes-agent.ts +45 -0
  56. package/examples/llm-params.ts +69 -0
  57. package/examples/mcp-agent.ts +84 -0
  58. package/examples/mcp-gateway.ts +35 -0
  59. package/examples/multi-agent.ts +73 -0
  60. package/examples/multi-endpoint.ts +79 -0
  61. package/examples/pom-prompt.ts +71 -0
  62. package/examples/prefab-concierge.ts +47 -0
  63. package/examples/prefab-faq.ts +54 -0
  64. package/examples/prefab-info-gatherer.ts +33 -0
  65. package/examples/prefab-receptionist.ts +36 -0
  66. package/examples/prefab-survey.ts +68 -0
  67. package/examples/record-call.ts +67 -0
  68. package/examples/relay-demo.ts +33 -0
  69. package/examples/room-and-sip.ts +94 -0
  70. package/examples/serverless-lambda.ts +35 -0
  71. package/examples/session-state.ts +83 -0
  72. package/examples/simple-agent.ts +36 -0
  73. package/examples/simple-static.ts +29 -0
  74. package/examples/skills-demo.ts +38 -0
  75. package/examples/step-function-inheritance-demo.ts +124 -0
  76. package/examples/swaig-features.ts +187 -0
  77. package/examples/swml-service-routing.ts +66 -0
  78. package/examples/swml-service.ts +38 -0
  79. package/examples/tap.ts +68 -0
  80. package/examples/verb-methods.ts +45 -0
  81. package/examples/web-search-multi-instance.ts +72 -0
  82. package/examples/web-search.ts +38 -0
  83. package/examples/wikipedia.ts +36 -0
  84. package/livewire/README.md +140 -0
  85. package/livewire/docs/migration-guide.md +228 -0
  86. package/livewire/examples/livewire-basic-agent.ts +74 -0
  87. package/livewire/examples/livewire-handoff.ts +197 -0
  88. package/livewire/examples/livewire-multi-tool.ts +117 -0
  89. package/package.json +38 -0
  90. package/relay/README.md +70 -0
  91. package/relay/RELAY_IMPLEMENTATION_GUIDE.md +1257 -0
  92. package/relay/docs/call-methods.md +474 -0
  93. package/relay/docs/client-reference.md +142 -0
  94. package/relay/docs/events.md +134 -0
  95. package/relay/docs/getting-started.md +134 -0
  96. package/relay/docs/guide.md +306 -0
  97. package/relay/docs/messaging.md +182 -0
  98. package/relay/examples/relay-inbound.ts +66 -0
  99. package/relay/examples/relay-messaging.ts +71 -0
  100. package/relay/examples/relay-outbound.ts +76 -0
  101. package/rest/README.md +95 -0
  102. package/rest/docs/calling.md +273 -0
  103. package/rest/docs/client-reference.md +107 -0
  104. package/rest/docs/compat.md +204 -0
  105. package/rest/docs/fabric.md +183 -0
  106. package/rest/docs/getting-started.md +110 -0
  107. package/rest/docs/guide.md +351 -0
  108. package/rest/docs/namespaces.md +285 -0
  109. package/rest/examples/rest-10dlc-registration.ts +161 -0
  110. package/rest/examples/rest-calling-ivr-and-ai.ts +102 -0
  111. package/rest/examples/rest-calling-play-and-record.ts +91 -0
  112. package/rest/examples/rest-client.ts +65 -0
  113. package/rest/examples/rest-compat-laml.ts +210 -0
  114. package/rest/examples/rest-datasphere-search.ts +82 -0
  115. package/rest/examples/rest-fabric-conferences-and-routing.ts +144 -0
  116. package/rest/examples/rest-fabric-subscribers-and-sip.ts +108 -0
  117. package/rest/examples/rest-fabric-swml-and-callflows.ts +99 -0
  118. package/rest/examples/rest-manage-resources.ts +65 -0
  119. package/rest/examples/rest-phone-number-management.ts +197 -0
  120. package/rest/examples/rest-queues-mfa-and-recordings.ts +143 -0
  121. package/rest/examples/rest-video-rooms.ts +186 -0
  122. package/src/AgentBase.ts +2489 -0
  123. package/src/AgentServer.ts +415 -0
  124. package/src/AuthHandler.ts +256 -0
  125. package/src/ConfigLoader.ts +447 -0
  126. package/src/ContextBuilder.ts +1150 -0
  127. package/src/DataMap.ts +449 -0
  128. package/src/FunctionResult.ts +866 -0
  129. package/src/Logger.ts +337 -0
  130. package/src/PomBuilder.ts +439 -0
  131. package/src/PromptManager.ts +133 -0
  132. package/src/SWMLHandler.ts +298 -0
  133. package/src/SWMLService.ts +717 -0
  134. package/src/SchemaUtils.ts +361 -0
  135. package/src/SecurityUtils.ts +153 -0
  136. package/src/ServerlessAdapter.ts +221 -0
  137. package/src/SessionManager.ts +311 -0
  138. package/src/SslConfig.ts +118 -0
  139. package/src/SwaigFunction.ts +276 -0
  140. package/src/SwmlBuilder.ts +258 -0
  141. package/src/SwmlVerbMethods.generated.ts +234 -0
  142. package/src/TypeInference.ts +181 -0
  143. package/src/WebService.ts +619 -0
  144. package/src/cli/agent-loader.ts +166 -0
  145. package/src/cli/mock-data.ts +111 -0
  146. package/src/cli/swaig-test.ts +452 -0
  147. package/src/generateVerbTypes.ts +322 -0
  148. package/src/index.ts +167 -0
  149. package/src/livewire/index.ts +950 -0
  150. package/src/prefabs/ConciergeAgent.ts +287 -0
  151. package/src/prefabs/FAQBotAgent.ts +384 -0
  152. package/src/prefabs/InfoGathererAgent.ts +339 -0
  153. package/src/prefabs/ReceptionistAgent.ts +366 -0
  154. package/src/prefabs/SurveyAgent.ts +646 -0
  155. package/src/prefabs/index.ts +27 -0
  156. package/src/relay/Action.ts +314 -0
  157. package/src/relay/Call.ts +854 -0
  158. package/src/relay/Deferred.ts +71 -0
  159. package/src/relay/Message.ts +148 -0
  160. package/src/relay/RelayClient.ts +1036 -0
  161. package/src/relay/RelayError.ts +14 -0
  162. package/src/relay/RelayEvent.ts +892 -0
  163. package/src/relay/constants.ts +132 -0
  164. package/src/relay/index.ts +123 -0
  165. package/src/relay/types.ts +149 -0
  166. package/src/rest/HttpClient.ts +103 -0
  167. package/src/rest/RestError.ts +31 -0
  168. package/src/rest/base/BaseResource.ts +19 -0
  169. package/src/rest/base/CrudResource.ts +51 -0
  170. package/src/rest/base/CrudWithAddresses.ts +26 -0
  171. package/src/rest/index.ts +200 -0
  172. package/src/rest/namespaces/addresses.ts +32 -0
  173. package/src/rest/namespaces/calling.ts +187 -0
  174. package/src/rest/namespaces/chat.ts +20 -0
  175. package/src/rest/namespaces/compat.ts +352 -0
  176. package/src/rest/namespaces/datasphere.ts +45 -0
  177. package/src/rest/namespaces/fabric.ts +222 -0
  178. package/src/rest/namespaces/imported-numbers.ts +20 -0
  179. package/src/rest/namespaces/logs.ts +84 -0
  180. package/src/rest/namespaces/lookup.ts +21 -0
  181. package/src/rest/namespaces/mfa.ts +30 -0
  182. package/src/rest/namespaces/number-groups.ts +38 -0
  183. package/src/rest/namespaces/phone-numbers.ts +44 -0
  184. package/src/rest/namespaces/project.ts +36 -0
  185. package/src/rest/namespaces/pubsub.ts +20 -0
  186. package/src/rest/namespaces/queues.ts +33 -0
  187. package/src/rest/namespaces/recordings.ts +28 -0
  188. package/src/rest/namespaces/registry.ts +101 -0
  189. package/src/rest/namespaces/short-codes.ts +28 -0
  190. package/src/rest/namespaces/sip-profile.ts +25 -0
  191. package/src/rest/namespaces/verified-callers.ts +27 -0
  192. package/src/rest/namespaces/video.ts +165 -0
  193. package/src/rest/pagination.ts +84 -0
  194. package/src/rest/types.ts +61 -0
  195. package/src/schema.json +12250 -0
  196. package/src/skills/SkillBase.ts +547 -0
  197. package/src/skills/SkillManager.ts +415 -0
  198. package/src/skills/SkillRegistry.ts +367 -0
  199. package/src/skills/builtin/api_ninjas_trivia.ts +280 -0
  200. package/src/skills/builtin/ask_claude.ts +241 -0
  201. package/src/skills/builtin/claude_skills.ts +978 -0
  202. package/src/skills/builtin/custom_skills.ts +312 -0
  203. package/src/skills/builtin/datasphere.ts +438 -0
  204. package/src/skills/builtin/datasphere_serverless.ts +339 -0
  205. package/src/skills/builtin/datetime.ts +130 -0
  206. package/src/skills/builtin/google_maps.ts +651 -0
  207. package/src/skills/builtin/index.ts +88 -0
  208. package/src/skills/builtin/info_gatherer.ts +405 -0
  209. package/src/skills/builtin/joke.ts +191 -0
  210. package/src/skills/builtin/math.ts +142 -0
  211. package/src/skills/builtin/mcp_gateway.ts +677 -0
  212. package/src/skills/builtin/native_vector_search.ts +901 -0
  213. package/src/skills/builtin/play_background_file.ts +358 -0
  214. package/src/skills/builtin/spider.ts +869 -0
  215. package/src/skills/builtin/swml_transfer.ts +635 -0
  216. package/src/skills/builtin/weather_api.ts +248 -0
  217. package/src/skills/builtin/web_search.ts +1074 -0
  218. package/src/skills/builtin/wikipedia_search.ts +299 -0
  219. package/src/skills/index.ts +12 -0
  220. package/src/types.ts +132 -0
  221. package/tests/AgentBase.test.ts +1093 -0
  222. package/tests/AgentServer.test.ts +126 -0
  223. package/tests/AuthHandler.test.ts +133 -0
  224. package/tests/ConfigLoader.test.ts +151 -0
  225. package/tests/ContextBuilder.test.ts +108 -0
  226. package/tests/DataMap.test.ts +367 -0
  227. package/tests/EphemeralSkillCopy.test.ts +107 -0
  228. package/tests/FunctionResult.test.ts +298 -0
  229. package/tests/GracefulShutdown.test.ts +46 -0
  230. package/tests/Logger.test.ts +420 -0
  231. package/tests/PomBuilder.test.ts +228 -0
  232. package/tests/ProxyDetection.test.ts +228 -0
  233. package/tests/SWMLService.test.ts +320 -0
  234. package/tests/SWMLVerbHandler.test.ts +523 -0
  235. package/tests/SchemaUtils.test.ts +106 -0
  236. package/tests/SchemaUtils.verb.test.ts +206 -0
  237. package/tests/SecurityUtils.test.ts +192 -0
  238. package/tests/ServerlessAdapter.test.ts +222 -0
  239. package/tests/SessionManager.test.ts +257 -0
  240. package/tests/SkillBaseFeatures.test.ts +130 -0
  241. package/tests/SkillMultiInstance.test.ts +102 -0
  242. package/tests/SkillParameterSchemas.test.ts +134 -0
  243. package/tests/SkillRegistrySchema.test.ts +84 -0
  244. package/tests/SslConfig.test.ts +97 -0
  245. package/tests/SwmlBuilder.test.ts +400 -0
  246. package/tests/TypeInference.test.ts +165 -0
  247. package/tests/VerbHandlerRegistry.test.ts +128 -0
  248. package/tests/cli/mock-data.test.ts +113 -0
  249. package/tests/cli/swaig-test.test.ts +108 -0
  250. package/tests/examples.test.ts +194 -0
  251. package/tests/fixtures/scrape-parity/README.md +53 -0
  252. package/tests/fixtures/scrape-parity/expected/01_simple_article.json +5 -0
  253. package/tests/fixtures/scrape-parity/expected/02_class_based_noise.json +5 -0
  254. package/tests/fixtures/scrape-parity/expected/03_nested_containers.json +5 -0
  255. package/tests/fixtures/scrape-parity/expected/04_bare_body.json +5 -0
  256. package/tests/fixtures/scrape-parity/expected/05_malformed.json +5 -0
  257. package/tests/fixtures/scrape-parity/expected/06_multi_class.json +5 -0
  258. package/tests/fixtures/scrape-parity/expected/07_anchor_pattern.json +5 -0
  259. package/tests/fixtures/scrape-parity/expected/08_inline_script.json +5 -0
  260. package/tests/fixtures/scrape-parity/expected/09_whitespace_nbsp.json +5 -0
  261. package/tests/fixtures/scrape-parity/expected/10_entity_unicode.json +5 -0
  262. package/tests/fixtures/scrape-parity/expected/11_cdata_comments.json +5 -0
  263. package/tests/fixtures/scrape-parity/expected/12_deep_nested_removals.json +5 -0
  264. package/tests/fixtures/scrape-parity/html/01_simple_article.html +18 -0
  265. package/tests/fixtures/scrape-parity/html/02_class_based_noise.html +18 -0
  266. package/tests/fixtures/scrape-parity/html/03_nested_containers.html +13 -0
  267. package/tests/fixtures/scrape-parity/html/04_bare_body.html +9 -0
  268. package/tests/fixtures/scrape-parity/html/05_malformed.html +11 -0
  269. package/tests/fixtures/scrape-parity/html/06_multi_class.html +18 -0
  270. package/tests/fixtures/scrape-parity/html/07_anchor_pattern.html +12 -0
  271. package/tests/fixtures/scrape-parity/html/08_inline_script.html +17 -0
  272. package/tests/fixtures/scrape-parity/html/09_whitespace_nbsp.html +21 -0
  273. package/tests/fixtures/scrape-parity/html/10_entity_unicode.html +10 -0
  274. package/tests/fixtures/scrape-parity/html/11_cdata_comments.html +13 -0
  275. package/tests/fixtures/scrape-parity/html/12_deep_nested_removals.html +24 -0
  276. package/tests/fixtures/scrape-parity/python_extract.py +109 -0
  277. package/tests/livewire/livewire.test.ts +780 -0
  278. package/tests/mcp.test.ts +221 -0
  279. package/tests/prefabs/prefabs.test.ts +1093 -0
  280. package/tests/relay/Action.test.ts +392 -0
  281. package/tests/relay/Call.test.ts +535 -0
  282. package/tests/relay/Deferred.test.ts +71 -0
  283. package/tests/relay/Message.test.ts +164 -0
  284. package/tests/relay/RelayClient.test.ts +779 -0
  285. package/tests/relay/RelayEvent.test.ts +463 -0
  286. package/tests/relay/helpers.ts +79 -0
  287. package/tests/rest/HttpClient.test.ts +274 -0
  288. package/tests/rest/RestError.test.ts +53 -0
  289. package/tests/rest/calling.test.ts +156 -0
  290. package/tests/rest/client.test.ts +197 -0
  291. package/tests/rest/compat.test.ts +335 -0
  292. package/tests/rest/datasphere.test.ts +71 -0
  293. package/tests/rest/fabric.test.ts +186 -0
  294. package/tests/rest/helpers.ts +95 -0
  295. package/tests/rest/logs.test.ts +68 -0
  296. package/tests/rest/pagination.test.ts +133 -0
  297. package/tests/rest/registry.test.ts +94 -0
  298. package/tests/rest/relay-rest.test.ts +290 -0
  299. package/tests/rest/video.test.ts +173 -0
  300. package/tests/setup.ts +6 -0
  301. package/tests/skills/SkillBase.test.ts +108 -0
  302. package/tests/skills/SkillManager.test.ts +268 -0
  303. package/tests/skills/SkillRegistry.test.ts +176 -0
  304. package/tests/skills/builtin.test.ts +1472 -0
  305. package/tests/skills/claude-skills.test.ts +54 -0
  306. package/tests/skills/custom-skills.test.ts +53 -0
  307. package/tests/skills/datasphere-serverless.test.ts +70 -0
  308. package/tests/skills/datasphere.test.ts +107 -0
  309. package/tests/skills/datetime.test.ts +101 -0
  310. package/tests/skills/google-maps.test.ts +78 -0
  311. package/tests/skills/info-gatherer.test.ts +411 -0
  312. package/tests/skills/joke.test.ts +81 -0
  313. package/tests/skills/math.test.ts +68 -0
  314. package/tests/skills/mcp-gateway.test.ts +101 -0
  315. package/tests/skills/play-background.test.ts +54 -0
  316. package/tests/skills/spider.test.ts +108 -0
  317. package/tests/skills/swml-transfer.test.ts +178 -0
  318. package/tests/skills/trivia.test.ts +54 -0
  319. package/tests/skills/vector-search.test.ts +135 -0
  320. package/tests/skills/weather-api.test.ts +77 -0
  321. package/tests/skills/web-search-parity.test.ts +59 -0
  322. package/tests/skills/web-search.test.ts +103 -0
  323. package/tests/skills/wikipedia.test.ts +63 -0
  324. package/tsconfig.json +18 -0
  325. package/vitest.config.ts +9 -0
@@ -0,0 +1,547 @@
1
+ /**
2
+ * SkillBase - Abstract base class for agent skills.
3
+ *
4
+ * Skills are modular capabilities that can be added to an agent.
5
+ * They define tools, prompt sections, hints, and global data.
6
+ */
7
+
8
+ import { randomBytes } from 'node:crypto';
9
+ import type { SwaigHandler } from '../SwaigFunction.js';
10
+ import type { FunctionResult } from '../FunctionResult.js';
11
+ import type { AgentBase } from '../AgentBase.js';
12
+ import { getLogger, type Logger } from '../Logger.js';
13
+
14
+ /** Configuration key-value pairs passed to a skill at construction time. */
15
+ export interface SkillConfig {
16
+ [key: string]: unknown;
17
+ }
18
+
19
+ /** Definition of a SWAIG tool provided by a skill. */
20
+ export interface SkillToolDefinition {
21
+ /** Unique tool name used in SWAIG function registration. */
22
+ name: string;
23
+ /** Human-readable description of what the tool does, shown to the AI. */
24
+ description: string;
25
+ /** Parameter schema for the tool, keyed by parameter name. */
26
+ parameters?: Record<string, unknown>;
27
+ /** Handler function invoked when the tool is called. */
28
+ handler: SwaigHandler;
29
+ /** Whether the tool requires secure (authenticated) invocation. */
30
+ secure?: boolean;
31
+ /** Filler phrases spoken while the tool executes, keyed by language. */
32
+ fillers?: Record<string, string[]>;
33
+ /** List of parameter names that are required. */
34
+ required?: string[];
35
+ /** If true, wait for any in-flight fillers to complete before executing the tool. */
36
+ wait_for_fillers?: boolean;
37
+ /** If true, suppress filler phrases while the tool executes. */
38
+ skip_fillers?: boolean;
39
+ /**
40
+ * When true, the SignalWire platform automatically invokes this tool when
41
+ * the call ends (hangup), regardless of whether the AI explicitly calls it.
42
+ * Equivalent to Python's `is_hangup_hook=True` in `define_tool()`.
43
+ * The flag is serialised as `"is_hangup_hook": true` in the SWAIG JSON.
44
+ */
45
+ isHangupHook?: boolean;
46
+ }
47
+
48
+ /** A section of prompt content injected into the agent's system prompt by a skill. */
49
+ export interface SkillPromptSection {
50
+ /** Section heading displayed in the prompt. */
51
+ title: string;
52
+ /** Optional body text for the section. */
53
+ body?: string;
54
+ /** Optional bullet points appended after the body. */
55
+ bullets?: string[];
56
+ /** If true, render bullets as a numbered list instead of unordered. */
57
+ numbered?: boolean;
58
+ }
59
+
60
+ /** Schema entry describing a single skill configuration parameter. */
61
+ export interface ParameterSchemaEntry {
62
+ /** JSON Schema type of the parameter value. */
63
+ type: 'string' | 'number' | 'integer' | 'boolean' | 'object' | 'array';
64
+ /** Human-readable description of the parameter. */
65
+ description: string;
66
+ /** Default value used when the parameter is not provided. */
67
+ default?: unknown;
68
+ /** Whether the parameter must be supplied. */
69
+ required?: boolean;
70
+ /** Whether the parameter should be hidden from user-facing output (e.g., API keys). */
71
+ hidden?: boolean;
72
+ /** Environment variable that can supply this parameter's value. */
73
+ env_var?: string;
74
+ /** Allowed values for the parameter. */
75
+ enum?: unknown[];
76
+ /** Minimum value (for numeric types). */
77
+ min?: number;
78
+ /** Maximum value (for numeric types). */
79
+ max?: number;
80
+ /** Item schema for array-type parameters. */
81
+ items?: Record<string, unknown>;
82
+ }
83
+
84
+ /**
85
+ * Abstract base class for agent skills.
86
+ *
87
+ * Skills are modular capabilities that can be added to an agent.
88
+ * They define tools, prompt sections, hints, and global data.
89
+ */
90
+ export abstract class SkillBase {
91
+ /**
92
+ * Unique skill name. Subclasses MUST override with a non-empty string.
93
+ *
94
+ * Python parity: `SKILL_NAME: str = None` at `core/skill_base.py:23`.
95
+ * Python raises `ValueError` in `__init__` when this is left as `None`;
96
+ * TS throws at construction when this is left as the empty default.
97
+ */
98
+ static SKILL_NAME: string = '';
99
+
100
+ /**
101
+ * Human-readable description of the skill. Subclasses MUST override.
102
+ *
103
+ * Python parity: `SKILL_DESCRIPTION: str = None` at `core/skill_base.py:24`.
104
+ */
105
+ static SKILL_DESCRIPTION: string = '';
106
+
107
+ /**
108
+ * Semantic version string. Subclasses may override; defaults to `"1.0.0"`.
109
+ *
110
+ * Python parity: `SKILL_VERSION: str = "1.0.0"` at `core/skill_base.py:25`.
111
+ */
112
+ static SKILL_VERSION: string = '1.0.0';
113
+
114
+ /**
115
+ * Packages required by the skill, checked at load time by `validatePackages()`.
116
+ *
117
+ * Python parity: `REQUIRED_PACKAGES: List[str] = []` at `core/skill_base.py:26`.
118
+ * In TS these are npm package names importable via dynamic `import()`.
119
+ */
120
+ static REQUIRED_PACKAGES: readonly string[] = [];
121
+
122
+ /**
123
+ * Environment variables required for the skill to function, checked at load
124
+ * time by `validateEnvVars()`.
125
+ *
126
+ * Python parity: `REQUIRED_ENV_VARS: List[str] = []` at `core/skill_base.py:27`.
127
+ */
128
+ static REQUIRED_ENV_VARS: readonly string[] = [];
129
+
130
+ /**
131
+ * Whether this skill type supports multiple simultaneous instances (e.g., with different tool_name).
132
+ *
133
+ * Python parity: `SUPPORTS_MULTIPLE_INSTANCES: bool = False` at `core/skill_base.py:30`.
134
+ */
135
+ static SUPPORTS_MULTIPLE_INSTANCES = false;
136
+
137
+ /**
138
+ * Get the parameter schema for this skill class, describing all accepted configuration options.
139
+ * Subclasses should override and call `super.getParameterSchema()` to include base parameters.
140
+ *
141
+ * Mirrors Python's `SkillBase.get_parameter_schema()` (skill_base.py:197-266):
142
+ * returns `swaig_fields` + `skip_prompt` for all skills, and additionally adds a
143
+ * `tool_name` entry with `default: cls.SKILL_NAME` for classes with
144
+ * `SUPPORTS_MULTIPLE_INSTANCES = true`.
145
+ *
146
+ * @returns Record mapping parameter names to their schema entries.
147
+ */
148
+ static getParameterSchema(): Record<string, ParameterSchemaEntry> {
149
+ const schema: Record<string, ParameterSchemaEntry> = {
150
+ swaig_fields: {
151
+ type: 'object',
152
+ description: 'Additional SWAIG fields to merge into each tool definition provided by this skill.',
153
+ default: {},
154
+ required: false,
155
+ },
156
+ skip_prompt: {
157
+ type: 'boolean',
158
+ description: 'When true, suppress all prompt sections from this skill.',
159
+ default: false,
160
+ required: false,
161
+ },
162
+ };
163
+ if (this.SUPPORTS_MULTIPLE_INSTANCES) {
164
+ schema['tool_name'] = {
165
+ type: 'string',
166
+ description: 'Custom name for this skill instance (for multiple instances).',
167
+ // Python `core/skill_base.py:261`: `default: cls.SKILL_NAME`.
168
+ default: this.SKILL_NAME || undefined,
169
+ required: false,
170
+ };
171
+ }
172
+ return schema;
173
+ }
174
+
175
+ /** The registered name of this skill type. */
176
+ readonly skillName: string;
177
+ /** Unique identifier for this skill instance (includes timestamp and random bytes). */
178
+ readonly instanceId: string;
179
+ /** Configuration options provided at construction time. */
180
+ protected config: SkillConfig;
181
+ /** Additional SWAIG fields extracted from config, merged into tool definitions. */
182
+ readonly swaigFields: Record<string, unknown>;
183
+ /**
184
+ * Reference to the agent that owns this skill.
185
+ * Set via `setAgent()` when the skill is added to an agent.
186
+ * Python equivalent: `self.agent` (set in `__init__`).
187
+ *
188
+ * In the Python SDK `agent` is always non-null because it is injected in the
189
+ * constructor. In the TypeScript SDK the SkillManager always calls
190
+ * `setAgent()` before `setup()`, so subclasses can rely on `getAgent()` being
191
+ * safe to call inside `setup()` and any method invoked after it.
192
+ */
193
+ protected agent?: AgentBase;
194
+ /**
195
+ * Logger scoped to this skill. Python equivalent: `self.logger = get_logger(...)`
196
+ * set in `SkillBase.__init__` so every subclass can call `self.logger.info(...)`.
197
+ */
198
+ protected readonly logger: Logger;
199
+ private _initialized = false;
200
+
201
+ /**
202
+ * Tools registered imperatively via `defineTool()`.
203
+ *
204
+ * Python parity: Python's `SkillBase.register_tools()` is a `@abstractmethod` that
205
+ * calls `self.agent.define_tool(...)` (or `self.define_tool(...)`) once per tool.
206
+ * In TypeScript the tool pipeline is declarative (pull model): `SkillManager`
207
+ * calls `getTools()` at SWML render time. Skills that want to build their tool
208
+ * list imperatively (e.g. to branch on config at setup time) can push into this
209
+ * collection via `defineTool()`; the default `getTools()` returns it.
210
+ */
211
+ protected _dynamicTools: SkillToolDefinition[] = [];
212
+
213
+ /**
214
+ * Return the agent that owns this skill, asserting it is non-null.
215
+ * Equivalent to accessing `self.agent` in Python, where the agent reference
216
+ * is always set before `setup()` is called.
217
+ *
218
+ * The SkillManager lifecycle guarantees that `setAgent()` is called before
219
+ * `setup()`, so this method is safe to use inside `setup()` and in any
220
+ * tool handler invoked during an active agent session.
221
+ *
222
+ * @returns The owning `AgentBase` instance.
223
+ * @throws {Error} If called before `setAgent()` (i.e., before the skill is
224
+ * attached to an agent by the SkillManager).
225
+ */
226
+ protected getAgent(): AgentBase {
227
+ if (!this.agent) {
228
+ throw new Error(
229
+ `SkillBase.getAgent() called before setAgent() on skill "${this.skillName}". ` +
230
+ 'Ensure getAgent() is only called from setup() or tool handlers, ' +
231
+ 'where the SkillManager has already attached the agent.',
232
+ );
233
+ }
234
+ return this.agent;
235
+ }
236
+
237
+ /**
238
+ * Create a new skill instance.
239
+ *
240
+ * Python parity: `core/skill_base.py:32-43`.
241
+ * Python `__init__` raises `ValueError` if `SKILL_NAME` or `SKILL_DESCRIPTION`
242
+ * is left as `None` on the subclass. TS throws the equivalent when the static
243
+ * defaults haven't been overridden.
244
+ *
245
+ * @param config - Optional configuration key-value pairs (Python: `params`).
246
+ */
247
+ constructor(config?: SkillConfig) {
248
+ const klass = this.constructor as typeof SkillBase;
249
+ if (!klass.SKILL_NAME) {
250
+ throw new Error(
251
+ `${klass.name} must define static SKILL_NAME ` +
252
+ `(Python equivalent: core/skill_base.py:23,33-34).`,
253
+ );
254
+ }
255
+ if (!klass.SKILL_DESCRIPTION) {
256
+ throw new Error(
257
+ `${klass.name} must define static SKILL_DESCRIPTION ` +
258
+ `(Python equivalent: core/skill_base.py:24,35-36).`,
259
+ );
260
+ }
261
+
262
+ this.skillName = klass.SKILL_NAME;
263
+ this.config = { ...(config ?? {}) };
264
+ this.instanceId = `${klass.SKILL_NAME}-${Date.now().toString(36)}-${randomBytes(4).toString('hex')}`;
265
+ this.logger = getLogger(`signalwire.skills.${klass.SKILL_NAME}`);
266
+
267
+ // Extract swaig_fields from config (matches Python's self.swaig_fields = self.params.pop('swaig_fields', {}))
268
+ this.swaigFields = (this.config['swaig_fields'] as Record<string, unknown>) ?? {};
269
+ delete this.config['swaig_fields'];
270
+ }
271
+
272
+ /**
273
+ * Setup the skill. Called when the skill is added to an agent.
274
+ * Override to perform initialization (API connections, config validation, etc.)
275
+ * @returns `true` if setup succeeded, `false` otherwise.
276
+ * Python equivalent: abstract `setup() -> bool`.
277
+ */
278
+ async setup(): Promise<boolean> {
279
+ return true;
280
+ }
281
+
282
+ /**
283
+ * Return the SWAIG tool definitions this skill provides.
284
+ *
285
+ * Default implementation returns tools registered imperatively via
286
+ * `defineTool()`. Skills using the declarative pattern override this
287
+ * method to return a static array built from their config.
288
+ *
289
+ * Python parity: replaces the `@abstractmethod register_tools()` contract
290
+ * — Python skills call `self.define_tool(...)` inside `register_tools()`;
291
+ * TypeScript skills either call `this.defineTool(...)` in `setup()` (and
292
+ * let the default `getTools()` return them) or override `getTools()`
293
+ * directly.
294
+ *
295
+ * @returns Array of tool definitions to register with the agent.
296
+ */
297
+ getTools(): SkillToolDefinition[] {
298
+ return [...this._dynamicTools];
299
+ }
300
+
301
+ /**
302
+ * Imperatively register a tool with this skill.
303
+ *
304
+ * Python parity: `core/skill_base.py:58` `def define_tool(self, **kwargs)`.
305
+ * Merges `this.swaigFields` into the tool definition (explicit fields on
306
+ * `toolDef` take precedence), then pushes the result into `_dynamicTools`
307
+ * so the default `getTools()` returns it at SWML render time.
308
+ *
309
+ * Intended for skills whose tool shape depends on config evaluated at
310
+ * `setup()` time. Skills with a static tool list should override
311
+ * `getTools()` instead.
312
+ *
313
+ * @param toolDef - The tool definition to register. Must include at
314
+ * minimum `name`, `description`, `parameters`, and `handler`.
315
+ */
316
+ protected defineTool(toolDef: SkillToolDefinition): void {
317
+ const swaigDefaults = this.swaigFields as Partial<SkillToolDefinition>;
318
+ const merged: SkillToolDefinition = {
319
+ ...swaigDefaults,
320
+ ...toolDef,
321
+ };
322
+ this._dynamicTools.push(merged);
323
+ }
324
+
325
+ /**
326
+ * Optional DataMap-style tool definitions. Skills that build their own
327
+ * SWAIG function dicts (e.g. via `DataMap.toSwaigFunction()`) return them
328
+ * here and `AgentBase.addSkill()` registers each via `registerSwaigFunction`.
329
+ *
330
+ * Python equivalent: the direct `self.agent.register_swaig_function(fn)`
331
+ * call inside `register_tools()` (e.g. `skills/datasphere_serverless/skill.py:210`).
332
+ * Default returns `[]` — skills using only the declarative `getTools()` path
333
+ * do not need to override this.
334
+ *
335
+ * @returns Array of fully-built SWAIG function dicts.
336
+ */
337
+ getDataMapTools(): Record<string, unknown>[] {
338
+ return [];
339
+ }
340
+
341
+ /**
342
+ * Get prompt sections to inject into the agent's system prompt.
343
+ * Respects the `skip_prompt` config option — returns `[]` if set to `true`.
344
+ * Subclasses should override `_getPromptSections()` instead of this method.
345
+ * @returns Array of prompt sections with titles, bodies, and bullets.
346
+ */
347
+ getPromptSections(): SkillPromptSection[] {
348
+ if (this.config['skip_prompt'] === true) {
349
+ return [];
350
+ }
351
+ return this._getPromptSections();
352
+ }
353
+
354
+ /**
355
+ * Internal method returning this skill's prompt sections.
356
+ * Override this in subclasses instead of `getPromptSections()`.
357
+ * @returns Array of prompt sections with titles, bodies, and bullets.
358
+ */
359
+ protected _getPromptSections(): SkillPromptSection[] {
360
+ return [];
361
+ }
362
+
363
+ /**
364
+ * Get speech recognition hints relevant to this skill.
365
+ * @returns Array of hint strings to improve speech recognition accuracy.
366
+ */
367
+ getHints(): string[] {
368
+ return [];
369
+ }
370
+
371
+ /**
372
+ * Get global data to merge into the agent's global data store.
373
+ * @returns Key-value pairs to be merged into the agent's global data.
374
+ */
375
+ getGlobalData(): Record<string, unknown> {
376
+ return {};
377
+ }
378
+
379
+ /**
380
+ * Get the instance key used for deduplication in the SkillManager.
381
+ *
382
+ * For single-instance skills (`SUPPORTS_MULTIPLE_INSTANCES = false`), returns
383
+ * the skill name. For multi-instance skills, returns `${skillName}_${toolName}`
384
+ * using the `tool_name` config (falls back to the skill name).
385
+ *
386
+ * Matches Python's `SkillBase.get_instance_key()` default (`skill_base.py:141-146`).
387
+ * Multi-instance subclasses only need to override when their key derivation
388
+ * depends on config beyond `tool_name`.
389
+ *
390
+ * @returns A unique key identifying this skill instance.
391
+ */
392
+ getInstanceKey(): string {
393
+ const SkillClass = this.constructor as typeof SkillBase;
394
+ if (!SkillClass.SUPPORTS_MULTIPLE_INSTANCES) {
395
+ return this.skillName;
396
+ }
397
+ const toolName = (this.config['tool_name'] as string | undefined) ?? this.skillName;
398
+ return `${this.skillName}_${toolName}`;
399
+ }
400
+
401
+ /**
402
+ * Get the namespaced key for storing per-skill data in global_data.
403
+ * @returns A string like "skill:datetime" or "skill:my_prefix".
404
+ */
405
+ getSkillNamespace(): string {
406
+ const prefix = this.config['prefix'] as string | undefined;
407
+ return `skill:${prefix ?? this.getInstanceKey()}`;
408
+ }
409
+
410
+ /**
411
+ * Read this skill's data from a raw call data object's global_data.
412
+ * @param rawData - The raw request data containing global_data.
413
+ * @returns The skill's stored data, or an empty object if not found.
414
+ */
415
+ getSkillData(rawData: Record<string, unknown>): Record<string, unknown> {
416
+ const globalData = rawData['global_data'] as Record<string, unknown> | undefined;
417
+ if (!globalData) return {};
418
+ return (globalData[this.getSkillNamespace()] as Record<string, unknown>) ?? {};
419
+ }
420
+
421
+ /**
422
+ * Update this skill's namespaced data on a FunctionResult via updateGlobalData.
423
+ * @param result - The FunctionResult to update.
424
+ * @param data - The data to store under this skill's namespace.
425
+ * @returns The FunctionResult for chaining.
426
+ */
427
+ updateSkillData(result: FunctionResult, data: Record<string, unknown>): FunctionResult {
428
+ return result.updateGlobalData({ [this.getSkillNamespace()]: data });
429
+ }
430
+
431
+ /**
432
+ * Cleanup resources. Called when the skill is removed from an agent.
433
+ */
434
+ async cleanup(): Promise<void> {
435
+ // Default no-op
436
+ }
437
+
438
+ /**
439
+ * Validate that all required environment variables declared on the skill class
440
+ * are set in the current process environment.
441
+ *
442
+ * Python parity: `core/skill_base.py:103-110` reads `self.REQUIRED_ENV_VARS`
443
+ * directly. TS reads the same static from the class.
444
+ *
445
+ * Returns the list of missing variable names so callers can produce actionable
446
+ * error messages. This differs from Python's `validate_env_vars() -> bool`
447
+ * return shape; {@link hasAllEnvVars} is the boolean equivalent.
448
+ *
449
+ * @returns Array of missing environment variable names (empty if all are present).
450
+ */
451
+ validateEnvVars(): string[] {
452
+ const klass = this.constructor as typeof SkillBase;
453
+ const missing: string[] = [];
454
+ for (const envVar of klass.REQUIRED_ENV_VARS) {
455
+ if (!process.env[envVar]) {
456
+ missing.push(envVar);
457
+ }
458
+ }
459
+ // Python parity: core/skill_base.py:107-109 logs an error line when any
460
+ // required env vars are missing. Mirror that here so both SDKs produce
461
+ // the same diagnostic signal during skill setup.
462
+ if (missing.length > 0) {
463
+ this.logger.error(`Missing required environment variables: ${missing.join(', ')}`);
464
+ }
465
+ return missing;
466
+ }
467
+
468
+ /**
469
+ * Check if the skill has been initialized by the SkillManager.
470
+ * @returns True if setup() has completed and the skill is marked initialized.
471
+ */
472
+ isInitialized(): boolean {
473
+ return this._initialized;
474
+ }
475
+
476
+ /**
477
+ * Mark the skill as initialized (called by SkillManager).
478
+ */
479
+ markInitialized(): void {
480
+ this._initialized = true;
481
+ }
482
+
483
+ /**
484
+ * Get a configuration value by key, falling back to a default if not set.
485
+ * @param key - The configuration key to look up.
486
+ * @param defaultValue - Value to return if the key is not present.
487
+ * @returns The configuration value cast to type T, or the default value.
488
+ */
489
+ getConfig<T = unknown>(key: string, defaultValue?: T): T {
490
+ return (this.config[key] !== undefined ? this.config[key] : defaultValue) as T;
491
+ }
492
+
493
+ /**
494
+ * Set the agent reference for this skill.
495
+ * Called by the SkillManager/AgentBase when the skill is attached to an agent.
496
+ * Python equivalent: `self.agent = agent` in `__init__`.
497
+ * @param agent - The agent that owns this skill.
498
+ */
499
+ setAgent(agent: AgentBase): void {
500
+ this.agent = agent;
501
+ }
502
+
503
+ /**
504
+ * Check if all required environment variables are present.
505
+ * Convenience wrapper around `validateEnvVars()` that returns a boolean,
506
+ * matching the Python `validate_env_vars() -> bool` return type.
507
+ * @returns `true` if all required env vars are set, `false` otherwise.
508
+ */
509
+ hasAllEnvVars(): boolean {
510
+ return this.validateEnvVars().length === 0;
511
+ }
512
+
513
+ /**
514
+ * Validate that all required packages declared on the skill class can be imported.
515
+ *
516
+ * Python parity: `core/skill_base.py:112-124` reads `self.REQUIRED_PACKAGES`
517
+ * directly and tries `importlib.import_module(pkg)` for each; TS does the
518
+ * equivalent with a dynamic `import()`.
519
+ *
520
+ * @returns Array of package names that could not be imported (empty if all present).
521
+ */
522
+ async validatePackages(): Promise<string[]> {
523
+ const klass = this.constructor as typeof SkillBase;
524
+ const missing: string[] = [];
525
+ for (const pkg of klass.REQUIRED_PACKAGES) {
526
+ try {
527
+ await import(pkg);
528
+ } catch {
529
+ missing.push(pkg);
530
+ }
531
+ }
532
+ if (missing.length > 0) {
533
+ this.logger.error(`Missing required packages: ${missing.join(', ')}`);
534
+ }
535
+ return missing;
536
+ }
537
+
538
+ /**
539
+ * Check if all required packages declared in the manifest are available.
540
+ * Convenience wrapper around `validatePackages()` that returns a boolean,
541
+ * matching the Python `validate_packages() -> bool` return type.
542
+ * @returns `true` if all required packages are importable, `false` otherwise.
543
+ */
544
+ async hasAllPackages(): Promise<boolean> {
545
+ return (await this.validatePackages()).length === 0;
546
+ }
547
+ }