@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,448 @@
1
+ # CLI Guide
2
+
3
+ Complete guide to the `swaig-test` command-line tool for testing SignalWire AI agents locally without making a phone call.
4
+
5
+ ---
6
+
7
+ ## Table of Contents
8
+
9
+ - [Overview](#overview)
10
+ - [Installation and Usage](#installation-and-usage)
11
+ - [Agent Discovery](#agent-discovery)
12
+ - [Discovery Order](#discovery-order)
13
+ - [The --agent-class Flag](#the---agent-class-flag)
14
+ - [Commands](#commands)
15
+ - [--dump-swml](#--dump-swml)
16
+ - [--list-tools](#--list-tools)
17
+ - [--exec function_name](#--exec-function_name)
18
+ - [--list-agents](#--list-agents)
19
+ - [Execution Options](#execution-options)
20
+ - [Function Arguments (--arg)](#function-arguments---arg)
21
+ - [Call Metadata Overrides](#call-metadata-overrides)
22
+ - [Post Data Overrides (--override)](#post-data-overrides---override)
23
+ - [Mock Data](#mock-data)
24
+ - [Full Mock Post Data](#full-mock-post-data)
25
+ - [Minimal Mock Post Data](#minimal-mock-post-data)
26
+ - [MockCallOptions](#mockcalloptions)
27
+ - [Output Formatting](#output-formatting)
28
+ - [Route Override](#route-override)
29
+ - [Environment Variables](#environment-variables)
30
+ - [Serverless Simulation](#serverless-simulation)
31
+ - [Examples](#examples)
32
+
33
+ ---
34
+
35
+ ## Overview
36
+
37
+ `swaig-test` is a CLI tool for testing SignalWire AI agents locally. It dynamically imports your agent module, generates mock call data, and lets you:
38
+
39
+ - **Dump the SWML document** your agent produces, so you can inspect its full configuration.
40
+ - **List all registered tools** with their descriptions and parameter schemas.
41
+ - **Execute a specific tool** with custom arguments and inspect the result.
42
+ - **List all agents** exported from a module file.
43
+
44
+ This allows you to iterate on your agent's configuration, prompt, and tool handlers without setting up a phone number, making a call, or deploying to a server.
45
+
46
+ **Source files:**
47
+
48
+ - `src/cli/swaig-test.ts` -- CLI entry point and argument parser.
49
+ - `src/cli/agent-loader.ts` -- Agent discovery via dynamic import with duck-typing.
50
+ - `src/cli/mock-data.ts` -- Mock call data generation.
51
+
52
+ ---
53
+
54
+ ## Installation and Usage
55
+
56
+ Run the CLI via `npx tsx` during development:
57
+
58
+ ```bash
59
+ npx tsx src/cli/swaig-test.ts <agent-path> [options]
60
+ ```
61
+
62
+ If the project has been built, you can run the compiled JavaScript directly:
63
+
64
+ ```bash
65
+ node dist/cli/swaig-test.js <agent-path> [options]
66
+ ```
67
+
68
+ The `<agent-path>` is the path to your agent module file (TypeScript or JavaScript). It is the first positional argument and is required for all commands except `--help`.
69
+
70
+ Show help:
71
+
72
+ ```bash
73
+ npx tsx src/cli/swaig-test.ts --help
74
+ ```
75
+
76
+ ---
77
+
78
+ ## Agent Discovery
79
+
80
+ The CLI uses dynamic `import()` to load your agent module, then applies a series of duck-typing heuristics to find an `AgentBase` instance. An object is considered an agent instance if it has `renderSwml`, `defineTool`, and `getPrompt` methods. A constructor function is considered an agent class if its `prototype` has those same methods.
81
+
82
+ ### Discovery Order
83
+
84
+ When no `--agent-class` flag is provided, the loader tries these strategies in order and uses the first match:
85
+
86
+ | Priority | Strategy | Description |
87
+ |---|---|---|
88
+ | 1 | Named export `agent` (instance) | Checks `module.agent` and verifies it is an agent instance via duck-typing. |
89
+ | 2 | Default export (instance) | Checks `module.default` and verifies it is an agent instance. |
90
+ | 3 | Any exported instance | Iterates over all exports; uses the first agent instance found. |
91
+ | 4 | Default export (class) | If `module.default` is an agent class, instantiates it with `{ name: 'cli-agent' }`. |
92
+ | 5 | Any exported class | Iterates over all exports; instantiates the first agent class found with `{ name: 'cli-agent' }`. |
93
+
94
+ ### The --agent-class Flag
95
+
96
+ Force the CLI to instantiate a specific class by name:
97
+
98
+ ```bash
99
+ npx tsx src/cli/swaig-test.ts my-agents.ts --agent-class SalesAgent --dump-swml
100
+ ```
101
+
102
+ The loader looks for a named export matching the class name and instantiates it.
103
+
104
+ ---
105
+
106
+ ## Commands
107
+
108
+ ### --dump-swml
109
+
110
+ Render and print the full SWML document the agent produces. This includes the complete 5-phase call flow, all tool definitions, the prompt, hints, languages, and all AI configuration.
111
+
112
+ ```bash
113
+ npx tsx src/cli/swaig-test.ts examples/simple_agent.ts --dump-swml
114
+ ```
115
+
116
+ Output is pretty-printed JSON.
117
+
118
+ ### --list-tools
119
+
120
+ List all registered tools with their descriptions, parameter schemas, and metadata. Shows both handler-based tools (`defineTool()`) and DataMap tools.
121
+
122
+ ```bash
123
+ npx tsx src/cli/swaig-test.ts examples/simple_agent.ts --list-tools
124
+ ```
125
+
126
+ Example output:
127
+
128
+ ```
129
+ Tools registered on agent 'my-agent':
130
+
131
+ 1. get_weather
132
+ Description: Get the current weather for a city
133
+ Parameters:
134
+ city (string, required): City name
135
+ units (string, optional): Temperature units [celsius, fahrenheit]
136
+
137
+ 2. check_order (DataMap)
138
+ Description: Check order status
139
+ Parameters:
140
+ order_id (string, required): Order number
141
+ ```
142
+
143
+ ### --exec function_name
144
+
145
+ Execute a specific tool handler with the provided arguments and display the result.
146
+
147
+ ```bash
148
+ npx tsx src/cli/swaig-test.ts examples/simple_agent.ts \
149
+ --exec get_weather \
150
+ --arg city=Austin \
151
+ --arg units=fahrenheit
152
+ ```
153
+
154
+ ### --list-agents
155
+
156
+ List all agent classes and instances exported from a module.
157
+
158
+ ```bash
159
+ npx tsx src/cli/swaig-test.ts examples/multi_agent_server.ts --list-agents
160
+ ```
161
+
162
+ ```bash
163
+ # With verbose details
164
+ npx tsx src/cli/swaig-test.ts examples/multi_agent_server.ts --list-agents --verbose
165
+ ```
166
+
167
+ ---
168
+
169
+ ## Execution Options
170
+
171
+ ### Function Arguments (--arg)
172
+
173
+ Pass arguments as `key=value` pairs:
174
+
175
+ ```bash
176
+ --arg city=Austin --arg units=fahrenheit
177
+ ```
178
+
179
+ For JSON values:
180
+
181
+ ```bash
182
+ --arg data='{"nested":"value"}'
183
+ ```
184
+
185
+ Arguments are parsed as strings by default. The CLI attempts JSON parsing for values that look like objects or arrays.
186
+
187
+ ### Call Metadata Overrides
188
+
189
+ Override fields in the mock call data:
190
+
191
+ ```bash
192
+ # Override the caller ID
193
+ --caller-id "+15551234567"
194
+
195
+ # Override the call direction
196
+ --direction inbound
197
+
198
+ # Override the SIP from address
199
+ --from-addr "sip:user@example.com"
200
+ ```
201
+
202
+ ### Post Data Overrides (--override)
203
+
204
+ Override specific fields in the mock post_data using dot notation:
205
+
206
+ ```bash
207
+ --override "call.call_id=custom-call-123"
208
+ --override "call.from=+15559876543"
209
+ --override "metadata.tenant=acme"
210
+ ```
211
+
212
+ ---
213
+
214
+ ## Mock Data
215
+
216
+ ### Full Mock Post Data
217
+
218
+ By default, `swaig-test` generates a comprehensive mock post_data payload that simulates a real SignalWire SWAIG request:
219
+
220
+ ```typescript
221
+ {
222
+ function: 'get_weather',
223
+ argument: { city: 'Austin' },
224
+ call_id: 'mock-call-uuid',
225
+ call: {
226
+ call_id: 'mock-call-uuid',
227
+ node_id: 'mock-node-uuid',
228
+ segment_id: 'mock-segment-uuid',
229
+ from: '+15551234567',
230
+ to: '+15559876543',
231
+ direction: 'inbound',
232
+ type: 'phone',
233
+ state: 'answered',
234
+ },
235
+ meta_data: {},
236
+ caller_id_name: 'Mock Caller',
237
+ caller_id_number: '+15551234567',
238
+ }
239
+ ```
240
+
241
+ ### Minimal Mock Post Data
242
+
243
+ Use `--minimal` to generate a stripped-down post_data with only the essential fields:
244
+
245
+ ```bash
246
+ npx tsx src/cli/swaig-test.ts my-agent.ts --exec get_weather --arg city=Austin --minimal
247
+ ```
248
+
249
+ ### MockCallOptions
250
+
251
+ The mock data generator accepts options for customizing the simulated call:
252
+
253
+ | Option | Type | Description |
254
+ |--------|------|-------------|
255
+ | `callId` | `string` | Custom call ID. |
256
+ | `from` | `string` | Caller number. |
257
+ | `to` | `string` | Destination number. |
258
+ | `direction` | `string` | `"inbound"` or `"outbound"`. |
259
+ | `callerIdName` | `string` | Caller display name. |
260
+ | `sipFrom` | `string` | SIP From address. |
261
+
262
+ ---
263
+
264
+ ## Output Formatting
265
+
266
+ ### Default (Human-Readable)
267
+
268
+ The default output is formatted for readability with section headers, colored output, and indented JSON.
269
+
270
+ ### --json
271
+
272
+ Output raw JSON for machine processing:
273
+
274
+ ```bash
275
+ npx tsx src/cli/swaig-test.ts my-agent.ts --exec get_weather --arg city=Austin --json
276
+ ```
277
+
278
+ ### --verbose
279
+
280
+ Enable detailed execution tracing. Shows the full request payload, handler execution details, and timing information. Also enables SDK logging output.
281
+
282
+ ```bash
283
+ npx tsx src/cli/swaig-test.ts my-agent.ts --exec get_weather --arg city=Austin --verbose
284
+ ```
285
+
286
+ ---
287
+
288
+ ## Route Override
289
+
290
+ When testing an agent that uses a non-root route, specify the route:
291
+
292
+ ```bash
293
+ npx tsx src/cli/swaig-test.ts my-agents.ts --route /support --dump-swml
294
+ ```
295
+
296
+ ---
297
+
298
+ ## Environment Variables
299
+
300
+ | Variable | Description |
301
+ |----------|-------------|
302
+ | `SIGNALWIRE_LOG_LEVEL` | Set log verbosity (`debug`, `info`, `warn`, `error`). Default: suppressed unless `--verbose`. |
303
+ | `SIGNALWIRE_LOG_MODE` | Set to `"off"` to fully suppress logs. Default: suppressed unless `--verbose`. |
304
+
305
+ The CLI automatically suppresses SDK logs unless `--verbose` is specified.
306
+
307
+ ---
308
+
309
+ ## Serverless Simulation
310
+
311
+ Test agents deployed as serverless functions by simulating the platform environment:
312
+
313
+ ```bash
314
+ # Simulate AWS Lambda
315
+ npx tsx src/cli/swaig-test.ts my-agent.ts --serverless lambda --dump-swml
316
+
317
+ # Simulate Google Cloud Functions
318
+ npx tsx src/cli/swaig-test.ts my-agent.ts --serverless gcf --exec my_tool --arg key=val
319
+
320
+ # Simulate Azure Functions
321
+ npx tsx src/cli/swaig-test.ts my-agent.ts --serverless azure --dump-swml
322
+
323
+ # Simulate CGI
324
+ npx tsx src/cli/swaig-test.ts my-agent.ts --serverless cgi --list-tools
325
+ ```
326
+
327
+ The serverless simulation sets up the appropriate environment variables and request format for each platform.
328
+
329
+ ---
330
+
331
+ ## Examples
332
+
333
+ ### Dump the SWML Document
334
+
335
+ ```bash
336
+ npx tsx src/cli/swaig-test.ts examples/simple_agent.ts --dump-swml
337
+ ```
338
+
339
+ ```json
340
+ {
341
+ "version": "1.0.0",
342
+ "sections": {
343
+ "main": [
344
+ { "answer": {} },
345
+ {
346
+ "ai": {
347
+ "prompt": { "text": "You are a helpful assistant." },
348
+ "SWAIG": {
349
+ "functions": [
350
+ {
351
+ "function": "get_weather",
352
+ "description": "Get current weather",
353
+ "parameters": { ... }
354
+ }
355
+ ]
356
+ }
357
+ }
358
+ }
359
+ ]
360
+ }
361
+ }
362
+ ```
363
+
364
+ ### List Registered Tools
365
+
366
+ ```bash
367
+ npx tsx src/cli/swaig-test.ts examples/skills_demo.ts --list-tools
368
+ ```
369
+
370
+ ### Execute a Tool
371
+
372
+ ```bash
373
+ # Execute with named arguments
374
+ npx tsx src/cli/swaig-test.ts examples/simple_agent.ts \
375
+ --exec get_weather \
376
+ --arg city=Austin \
377
+ --arg units=fahrenheit
378
+
379
+ # Execute with verbose output
380
+ npx tsx src/cli/swaig-test.ts examples/simple_agent.ts \
381
+ --exec get_weather \
382
+ --arg city=Austin \
383
+ --verbose
384
+ ```
385
+
386
+ ### Test with Custom Caller Data
387
+
388
+ ```bash
389
+ npx tsx src/cli/swaig-test.ts examples/simple_dynamic_agent.ts \
390
+ --dump-swml \
391
+ --caller-id "+15551234567" \
392
+ --override "call.direction=outbound"
393
+ ```
394
+
395
+ ### Simulate a SIP Call
396
+
397
+ ```bash
398
+ npx tsx src/cli/swaig-test.ts examples/room_and_sip_example.ts \
399
+ --dump-swml \
400
+ --from-addr "sip:sales@company.com"
401
+ ```
402
+
403
+ ### Test with Environment Variables
404
+
405
+ ```bash
406
+ WEATHER_API_KEY=abc123 npx tsx src/cli/swaig-test.ts \
407
+ examples/simple_agent.ts \
408
+ --exec get_weather \
409
+ --arg city=Austin
410
+ ```
411
+
412
+ ### Machine-Readable Output
413
+
414
+ ```bash
415
+ npx tsx src/cli/swaig-test.ts examples/simple_agent.ts \
416
+ --exec get_weather \
417
+ --arg city=Austin \
418
+ --json
419
+ ```
420
+
421
+ ### Discover Agents in a File
422
+
423
+ ```bash
424
+ # Just run the file with no other flags to discover agents
425
+ npx tsx src/cli/swaig-test.ts examples/multi_agent_server.ts
426
+
427
+ # Or explicitly list agents
428
+ npx tsx src/cli/swaig-test.ts examples/multi_agent_server.ts --list-agents
429
+ ```
430
+
431
+ ### Test a Specific Agent Class
432
+
433
+ ```bash
434
+ npx tsx src/cli/swaig-test.ts examples/multi_agent_server.ts \
435
+ --agent-class SupportAgent \
436
+ --dump-swml
437
+ ```
438
+
439
+ ### Test a DataMap Tool
440
+
441
+ ```bash
442
+ npx tsx src/cli/swaig-test.ts examples/data_map_demo.ts \
443
+ --exec get_weather \
444
+ --arg city=Austin \
445
+ --verbose
446
+ ```
447
+
448
+ DataMap tools are automatically detected and simulated -- the CLI makes real HTTP requests using the DataMap's webhook configuration, processes the response through the output template, and displays the result.