@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,452 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * swaig-test - CLI tool for testing SignalWire AI agents locally.
4
+ *
5
+ * Usage:
6
+ * swaig-test <agent-path> [options]
7
+ *
8
+ * Actions:
9
+ * --list-tools List all SWAIG functions with parameters
10
+ * --list-agents List all exported agents in a file
11
+ * --dump-swml Generate and output SWML document
12
+ * --exec <name> Execute a function (use --arg key=value for args)
13
+ *
14
+ * Options:
15
+ * --raw Raw JSON output (suppresses logs)
16
+ * --verbose Verbose output
17
+ * --format-json Format output as indented JSON
18
+ * --call-type sip|webrtc (default: webrtc)
19
+ * --call-direction inbound|outbound (default: inbound)
20
+ * --call-state active|ringing|hold (default: active)
21
+ * --call-id Override call ID
22
+ * --from-number Override from number
23
+ * --to-extension Override to extension
24
+ * --arg key=value Function argument (repeatable)
25
+ * --override k=v Override call data field (repeatable)
26
+ * --agent-class Name of specific agent class to use
27
+ * --route Route for agent (default: /)
28
+ * --env KEY=VALUE Set env var (repeatable)
29
+ * --env-file Load env vars from file
30
+ * --simulate-serverless <platform> Simulate serverless platform
31
+ */
32
+
33
+ import { loadAgent, listAgents } from './agent-loader.js';
34
+ import { generateFakePostData, generateMinimalPostData } from './mock-data.js';
35
+ import { suppressAllLogs, setGlobalLogLevel } from '../Logger.js';
36
+ import { ServerlessAdapter } from '../ServerlessAdapter.js';
37
+ import type { ServerlessPlatform } from '../ServerlessAdapter.js';
38
+
39
+ interface CliOptions {
40
+ agentPath: string;
41
+ action: 'list-tools' | 'list-agents' | 'dump-swml' | 'exec';
42
+ execName?: string;
43
+ raw: boolean;
44
+ verbose: boolean;
45
+ formatJson: boolean;
46
+ callType: 'sip' | 'webrtc';
47
+ callDirection: 'inbound' | 'outbound';
48
+ callState: string;
49
+ callId?: string;
50
+ fromNumber?: string;
51
+ toExtension?: string;
52
+ args: Record<string, unknown>;
53
+ overrides: Record<string, unknown>;
54
+ agentClass?: string;
55
+ route?: string;
56
+ envVars: Record<string, string>;
57
+ envFile?: string;
58
+ simulateServerless?: string;
59
+ }
60
+
61
+ function printUsage(): void {
62
+ console.log(`
63
+ swaig-test - CLI tool for testing SignalWire AI agents locally
64
+
65
+ Usage:
66
+ swaig-test <agent-path> [options]
67
+
68
+ Actions:
69
+ --list-tools List all SWAIG functions with parameters
70
+ --list-agents List all exported agents in a file
71
+ --dump-swml Generate and output SWML document
72
+ --exec <name> Execute a function (use --arg key=value for args)
73
+
74
+ Options:
75
+ --raw Raw JSON output (suppresses logs)
76
+ --verbose Verbose output
77
+ --format-json Format output as indented JSON
78
+ --call-type sip|webrtc (default: webrtc)
79
+ --call-direction inbound|outbound (default: inbound)
80
+ --call-state active|ringing|hold (default: active)
81
+ --call-id Override call ID
82
+ --from-number Override from number
83
+ --to-extension Override to extension
84
+ --arg key=value Function argument (repeatable)
85
+ --override k=v Override call data field (repeatable)
86
+ --agent-class Name of specific agent class to use
87
+ --route Route for the agent
88
+ --env KEY=VALUE Set env var (repeatable)
89
+ --env-file Load env vars from file
90
+ --simulate-serverless <platform> Simulate serverless (lambda|gcf|azure|cgi)
91
+ --help Show this help message
92
+ `);
93
+ }
94
+
95
+ function parseArgs(argv: string[]): CliOptions {
96
+ const args = argv.slice(2); // skip node + script
97
+ if (args.length === 0 || args.includes('--help') || args.includes('-h')) {
98
+ printUsage();
99
+ process.exit(0);
100
+ }
101
+
102
+ const opts: CliOptions = {
103
+ agentPath: '',
104
+ action: 'dump-swml',
105
+ raw: false,
106
+ verbose: false,
107
+ formatJson: false,
108
+ callType: 'webrtc',
109
+ callDirection: 'inbound',
110
+ callState: 'active',
111
+ args: {},
112
+ overrides: {},
113
+ envVars: {},
114
+ };
115
+
116
+ let i = 0;
117
+
118
+ // First positional arg is the agent path
119
+ if (!args[0].startsWith('--')) {
120
+ opts.agentPath = args[0];
121
+ i = 1;
122
+ }
123
+
124
+ for (; i < args.length; i++) {
125
+ const arg = args[i];
126
+ switch (arg) {
127
+ case '--list-tools':
128
+ opts.action = 'list-tools';
129
+ break;
130
+ case '--list-agents':
131
+ opts.action = 'list-agents';
132
+ break;
133
+ case '--dump-swml':
134
+ opts.action = 'dump-swml';
135
+ break;
136
+ case '--exec':
137
+ opts.action = 'exec';
138
+ opts.execName = args[++i];
139
+ if (!opts.execName) {
140
+ console.error('Error: --exec requires a function name');
141
+ process.exit(1);
142
+ }
143
+ break;
144
+ case '--raw':
145
+ opts.raw = true;
146
+ break;
147
+ case '--verbose':
148
+ opts.verbose = true;
149
+ break;
150
+ case '--format-json':
151
+ opts.formatJson = true;
152
+ break;
153
+ case '--call-type':
154
+ opts.callType = args[++i] as 'sip' | 'webrtc';
155
+ break;
156
+ case '--call-direction':
157
+ opts.callDirection = args[++i] as 'inbound' | 'outbound';
158
+ break;
159
+ case '--call-state':
160
+ opts.callState = args[++i];
161
+ break;
162
+ case '--call-id':
163
+ opts.callId = args[++i];
164
+ break;
165
+ case '--from-number':
166
+ opts.fromNumber = args[++i];
167
+ break;
168
+ case '--to-extension':
169
+ opts.toExtension = args[++i];
170
+ break;
171
+ case '--agent-class':
172
+ opts.agentClass = args[++i];
173
+ break;
174
+ case '--route':
175
+ opts.route = args[++i];
176
+ break;
177
+ case '--simulate-serverless':
178
+ opts.simulateServerless = args[++i];
179
+ break;
180
+ case '--env-file':
181
+ opts.envFile = args[++i];
182
+ break;
183
+ case '--arg': {
184
+ const kv = args[++i];
185
+ if (!kv || !kv.includes('=')) {
186
+ console.error('Error: --arg requires key=value format');
187
+ process.exit(1);
188
+ }
189
+ const eqIdx = kv.indexOf('=');
190
+ const key = kv.slice(0, eqIdx);
191
+ const val = kv.slice(eqIdx + 1);
192
+ // Try to parse as JSON, fall back to string
193
+ try {
194
+ opts.args[key] = JSON.parse(val);
195
+ } catch {
196
+ opts.args[key] = val;
197
+ }
198
+ break;
199
+ }
200
+ case '--override': {
201
+ const kv = args[++i];
202
+ if (!kv || !kv.includes('=')) {
203
+ console.error('Error: --override requires key=value format');
204
+ process.exit(1);
205
+ }
206
+ const eqIdx = kv.indexOf('=');
207
+ const key = kv.slice(0, eqIdx);
208
+ const val = kv.slice(eqIdx + 1);
209
+ try {
210
+ opts.overrides[key] = JSON.parse(val);
211
+ } catch {
212
+ opts.overrides[key] = val;
213
+ }
214
+ break;
215
+ }
216
+ case '--env': {
217
+ const kv = args[++i];
218
+ if (!kv || !kv.includes('=')) {
219
+ console.error('Error: --env requires KEY=VALUE format');
220
+ process.exit(1);
221
+ }
222
+ const eqIdx = kv.indexOf('=');
223
+ opts.envVars[kv.slice(0, eqIdx)] = kv.slice(eqIdx + 1);
224
+ break;
225
+ }
226
+ default:
227
+ if (!opts.agentPath && !arg.startsWith('--')) {
228
+ opts.agentPath = arg;
229
+ } else {
230
+ console.error(`Unknown option: ${arg}`);
231
+ process.exit(1);
232
+ }
233
+ }
234
+ }
235
+
236
+ if (!opts.agentPath) {
237
+ console.error('Error: agent path is required');
238
+ printUsage();
239
+ process.exit(1);
240
+ }
241
+
242
+ return opts;
243
+ }
244
+
245
+ function loadEnvFile(filePath: string): void {
246
+ const { readFileSync } = require('node:fs');
247
+ const { resolve } = require('node:path');
248
+ const content = readFileSync(resolve(filePath), 'utf-8');
249
+ for (const line of content.split('\n')) {
250
+ const trimmed = line.trim();
251
+ if (!trimmed || trimmed.startsWith('#')) continue;
252
+ const eqIdx = trimmed.indexOf('=');
253
+ if (eqIdx > 0) {
254
+ const key = trimmed.slice(0, eqIdx).trim();
255
+ let val = trimmed.slice(eqIdx + 1).trim();
256
+ // Strip quotes
257
+ if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
258
+ val = val.slice(1, -1);
259
+ }
260
+ process.env[key] = val;
261
+ }
262
+ }
263
+ }
264
+
265
+ async function main(): Promise<void> {
266
+ const opts = parseArgs(process.argv);
267
+
268
+ if (opts.raw) {
269
+ suppressAllLogs(true);
270
+ } else if (opts.verbose) {
271
+ setGlobalLogLevel('debug');
272
+ }
273
+
274
+ // Apply env vars
275
+ if (opts.envFile) {
276
+ loadEnvFile(opts.envFile);
277
+ }
278
+ for (const [k, v] of Object.entries(opts.envVars)) {
279
+ process.env[k] = v;
280
+ }
281
+
282
+ // List agents action (doesn't need a loaded agent)
283
+ if (opts.action === 'list-agents') {
284
+ const agents = await listAgents(opts.agentPath);
285
+ if (opts.raw || opts.formatJson) {
286
+ console.log(JSON.stringify(agents, null, 2));
287
+ } else {
288
+ console.log(`\nExported agents in ${opts.agentPath}:\n`);
289
+ for (const name of agents) {
290
+ console.log(` ${name}`);
291
+ }
292
+ console.log();
293
+ }
294
+ return;
295
+ }
296
+
297
+ // Load agent
298
+ const agent = await loadAgent(opts.agentPath, opts.agentClass) as any;
299
+
300
+ // Apply --route override
301
+ if (opts.route && typeof agent.route !== 'undefined') {
302
+ agent.route = opts.route;
303
+ }
304
+
305
+ // Handle --simulate-serverless
306
+ if (opts.simulateServerless) {
307
+ const platform = opts.simulateServerless as ServerlessPlatform;
308
+ const adapter = new ServerlessAdapter(platform);
309
+ const app = agent.getApp();
310
+ const postData = generateFakePostData({
311
+ callType: opts.callType,
312
+ callDirection: opts.callDirection,
313
+ callState: opts.callState,
314
+ callId: opts.callId,
315
+ fromNumber: opts.fromNumber,
316
+ toExtension: opts.toExtension,
317
+ overrides: opts.overrides,
318
+ });
319
+ const event = {
320
+ httpMethod: 'POST',
321
+ path: agent.route ?? '/',
322
+ headers: {
323
+ 'content-type': 'application/json',
324
+ 'authorization': 'Basic ' + Buffer.from(`${agent.basicAuthCreds?.[0] ?? 'user'}:${agent.basicAuthCreds?.[1] ?? 'pass'}`).toString('base64'),
325
+ },
326
+ body: postData,
327
+ };
328
+ const response = await adapter.handleRequest(app, event);
329
+ if (opts.raw || opts.formatJson) {
330
+ try {
331
+ console.log(JSON.stringify(JSON.parse(response.body), null, 2));
332
+ } catch {
333
+ console.log(response.body);
334
+ }
335
+ } else {
336
+ console.log(`\n--- Serverless Simulation (${platform}) ---`);
337
+ console.log(`Status: ${response.statusCode}`);
338
+ console.log(`Headers: ${JSON.stringify(response.headers, null, 2)}`);
339
+ console.log('Body:');
340
+ try {
341
+ console.log(JSON.stringify(JSON.parse(response.body), null, 2));
342
+ } catch {
343
+ console.log(response.body);
344
+ }
345
+ console.log();
346
+ }
347
+ return;
348
+ }
349
+
350
+ switch (opts.action) {
351
+ case 'list-tools': {
352
+ if (typeof agent.getRegisteredTools !== 'function') {
353
+ console.log('This is a SWMLService (no tools). Use --dump-swml to see the SWML document.');
354
+ break;
355
+ }
356
+ const tools = agent.getRegisteredTools();
357
+ if (opts.raw || opts.formatJson) {
358
+ console.log(JSON.stringify(tools, null, 2));
359
+ } else {
360
+ if (tools.length === 0) {
361
+ console.log('No tools registered.');
362
+ } else {
363
+ console.log(`\nRegistered tools (${tools.length}):\n`);
364
+ for (const tool of tools) {
365
+ console.log(` ${tool.name}`);
366
+ console.log(` Description: ${tool.description}`);
367
+ if (tool.parameters && Object.keys(tool.parameters).length) {
368
+ console.log(` Parameters: ${JSON.stringify(tool.parameters, null, 6).replace(/\n/g, '\n ')}`);
369
+ }
370
+ console.log();
371
+ }
372
+ }
373
+ }
374
+ break;
375
+ }
376
+
377
+ case 'dump-swml': {
378
+ // SWMLService.renderSwml() returns an object; AgentBase.renderSwml() returns a string
379
+ let swmlJson: unknown;
380
+ if (typeof agent.getRegisteredTools !== 'function') {
381
+ // SWMLService — renderSwml returns object directly
382
+ swmlJson = agent.renderSwml();
383
+ } else {
384
+ // AgentBase — renderSwml(callId) returns JSON string
385
+ const postData = generateFakePostData({
386
+ callType: opts.callType,
387
+ callDirection: opts.callDirection,
388
+ callState: opts.callState,
389
+ callId: opts.callId,
390
+ fromNumber: opts.fromNumber,
391
+ toExtension: opts.toExtension,
392
+ overrides: opts.overrides,
393
+ });
394
+ swmlJson = JSON.parse(agent.renderSwml(postData['call_id'] as string));
395
+ }
396
+ if (opts.raw || opts.formatJson) {
397
+ console.log(JSON.stringify(swmlJson, null, 2));
398
+ } else {
399
+ console.log('\n--- SWML Document ---\n');
400
+ console.log(JSON.stringify(swmlJson, null, 2));
401
+ console.log();
402
+ }
403
+ break;
404
+ }
405
+
406
+ case 'exec': {
407
+ if (!opts.execName) {
408
+ console.error('Error: --exec requires a function name');
409
+ process.exit(1);
410
+ }
411
+
412
+ const tool = agent.getTool(opts.execName);
413
+ if (!tool) {
414
+ console.error(`Error: function '${opts.execName}' not found`);
415
+ const available = agent.getRegisteredTools().map((t: any) => t.name);
416
+ if (available.length) {
417
+ console.error(`Available functions: ${available.join(', ')}`);
418
+ }
419
+ process.exit(1);
420
+ }
421
+
422
+ const postData = generateMinimalPostData(opts.execName, opts.args, {
423
+ callId: opts.callId,
424
+ overrides: opts.overrides,
425
+ });
426
+
427
+ if (!opts.raw) {
428
+ console.log(`\nExecuting: ${opts.execName}`);
429
+ if (Object.keys(opts.args).length) {
430
+ console.log(`Arguments: ${JSON.stringify(opts.args)}`);
431
+ }
432
+ console.log();
433
+ }
434
+
435
+ const result = await tool.execute(opts.args, postData);
436
+
437
+ if (opts.raw || opts.formatJson) {
438
+ console.log(JSON.stringify(result, null, 2));
439
+ } else {
440
+ console.log('--- Result ---\n');
441
+ console.log(JSON.stringify(result, null, 2));
442
+ console.log();
443
+ }
444
+ break;
445
+ }
446
+ }
447
+ }
448
+
449
+ main().catch((err) => {
450
+ console.error(err.message ?? err);
451
+ process.exit(1);
452
+ });