@signalwire/sdk 2.0.0 → 2.0.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/AgentBase.d.ts +1045 -0
- package/dist/AgentBase.js +2375 -0
- package/dist/AgentBase.js.map +1 -0
- package/dist/AgentServer.d.ts +146 -0
- package/dist/AgentServer.js +388 -0
- package/dist/AgentServer.js.map +1 -0
- package/dist/AuthHandler.d.ts +127 -0
- package/dist/AuthHandler.js +212 -0
- package/dist/AuthHandler.js.map +1 -0
- package/dist/ConfigLoader.d.ts +170 -0
- package/dist/ConfigLoader.js +393 -0
- package/dist/ConfigLoader.js.map +1 -0
- package/dist/ContextBuilder.d.ts +652 -0
- package/dist/ContextBuilder.js +1115 -0
- package/dist/ContextBuilder.js.map +1 -0
- package/dist/DataMap.d.ts +271 -0
- package/dist/DataMap.js +430 -0
- package/dist/DataMap.js.map +1 -0
- package/dist/FunctionResult.d.ts +481 -0
- package/dist/FunctionResult.js +775 -0
- package/dist/FunctionResult.js.map +1 -0
- package/dist/Logger.d.ts +113 -0
- package/dist/Logger.js +320 -0
- package/dist/Logger.js.map +1 -0
- package/dist/PomBuilder.d.ts +208 -0
- package/dist/PomBuilder.js +409 -0
- package/dist/PomBuilder.js.map +1 -0
- package/dist/PromptManager.d.ts +85 -0
- package/dist/PromptManager.js +108 -0
- package/dist/PromptManager.js.map +1 -0
- package/dist/SWMLHandler.d.ts +159 -0
- package/dist/SWMLHandler.js +229 -0
- package/dist/SWMLHandler.js.map +1 -0
- package/dist/SWMLService.d.ts +326 -0
- package/dist/SWMLService.js +610 -0
- package/dist/SWMLService.js.map +1 -0
- package/dist/SchemaUtils.d.ts +108 -0
- package/dist/SchemaUtils.js +317 -0
- package/dist/SchemaUtils.js.map +1 -0
- package/dist/SecurityUtils.d.ts +60 -0
- package/{src/SecurityUtils.ts → dist/SecurityUtils.js} +82 -83
- package/dist/SecurityUtils.js.map +1 -0
- package/dist/ServerlessAdapter.d.ts +119 -0
- package/dist/ServerlessAdapter.js +188 -0
- package/dist/ServerlessAdapter.js.map +1 -0
- package/dist/SessionManager.d.ts +142 -0
- package/dist/SessionManager.js +260 -0
- package/dist/SessionManager.js.map +1 -0
- package/dist/SslConfig.d.ts +77 -0
- package/dist/SslConfig.js +100 -0
- package/dist/SslConfig.js.map +1 -0
- package/dist/SwaigFunction.d.ts +159 -0
- package/dist/SwaigFunction.js +209 -0
- package/dist/SwaigFunction.js.map +1 -0
- package/dist/SwmlBuilder.d.ts +165 -0
- package/dist/SwmlBuilder.js +247 -0
- package/dist/SwmlBuilder.js.map +1 -0
- package/dist/SwmlVerbMethods.generated.d.ts +254 -0
- package/dist/SwmlVerbMethods.generated.js +9 -0
- package/dist/SwmlVerbMethods.generated.js.map +1 -0
- package/dist/TypeInference.d.ts +71 -0
- package/dist/TypeInference.js +164 -0
- package/dist/TypeInference.js.map +1 -0
- package/dist/WebService.d.ts +148 -0
- package/dist/WebService.js +532 -0
- package/dist/WebService.js.map +1 -0
- package/dist/cli/agent-loader.d.ts +22 -0
- package/dist/cli/agent-loader.js +144 -0
- package/dist/cli/agent-loader.js.map +1 -0
- package/dist/cli/mock-data.d.ts +37 -0
- package/dist/cli/mock-data.js +80 -0
- package/dist/cli/mock-data.js.map +1 -0
- package/dist/cli/swaig-test.d.ts +32 -0
- package/dist/cli/swaig-test.js +418 -0
- package/dist/cli/swaig-test.js.map +1 -0
- package/dist/generateVerbTypes.d.ts +11 -0
- package/dist/generateVerbTypes.js +265 -0
- package/dist/generateVerbTypes.js.map +1 -0
- package/dist/index.d.ts +146 -0
- package/dist/index.js +152 -0
- package/dist/index.js.map +1 -0
- package/dist/livewire/index.d.ts +653 -0
- package/dist/livewire/index.js +992 -0
- package/dist/livewire/index.js.map +1 -0
- package/dist/prefabs/ConciergeAgent.d.ts +89 -0
- package/dist/prefabs/ConciergeAgent.js +245 -0
- package/dist/prefabs/ConciergeAgent.js.map +1 -0
- package/dist/prefabs/FAQBotAgent.d.ts +113 -0
- package/dist/prefabs/FAQBotAgent.js +329 -0
- package/dist/prefabs/FAQBotAgent.js.map +1 -0
- package/dist/prefabs/InfoGathererAgent.d.ts +126 -0
- package/dist/prefabs/InfoGathererAgent.js +287 -0
- package/dist/prefabs/InfoGathererAgent.js.map +1 -0
- package/dist/prefabs/ReceptionistAgent.d.ts +104 -0
- package/dist/prefabs/ReceptionistAgent.js +303 -0
- package/dist/prefabs/ReceptionistAgent.js.map +1 -0
- package/dist/prefabs/SurveyAgent.d.ts +148 -0
- package/dist/prefabs/SurveyAgent.js +540 -0
- package/dist/prefabs/SurveyAgent.js.map +1 -0
- package/{src/prefabs/index.ts → dist/prefabs/index.d.ts} +1 -15
- package/dist/prefabs/index.js +14 -0
- package/dist/prefabs/index.js.map +1 -0
- package/dist/relay/Action.d.ts +258 -0
- package/dist/relay/Action.js +402 -0
- package/dist/relay/Action.js.map +1 -0
- package/dist/relay/Call.d.ts +697 -0
- package/dist/relay/Call.js +1062 -0
- package/dist/relay/Call.js.map +1 -0
- package/dist/relay/Deferred.d.ts +44 -0
- package/dist/relay/Deferred.js +69 -0
- package/dist/relay/Deferred.js.map +1 -0
- package/dist/relay/Message.d.ts +103 -0
- package/dist/relay/Message.js +169 -0
- package/dist/relay/Message.js.map +1 -0
- package/dist/relay/RelayClient.d.ts +302 -0
- package/dist/relay/RelayClient.js +1019 -0
- package/dist/relay/RelayClient.js.map +1 -0
- package/dist/relay/RelayError.d.ts +15 -0
- package/dist/relay/RelayError.js +20 -0
- package/dist/relay/RelayError.js.map +1 -0
- package/dist/relay/RelayEvent.d.ts +254 -0
- package/dist/relay/RelayEvent.js +509 -0
- package/dist/relay/RelayEvent.js.map +1 -0
- package/dist/relay/constants.d.ts +90 -0
- package/{src/relay/constants.ts → dist/relay/constants.js} +11 -29
- package/dist/relay/constants.js.map +1 -0
- package/dist/relay/index.d.ts +16 -0
- package/dist/relay/index.js +18 -0
- package/dist/relay/index.js.map +1 -0
- package/dist/relay/types.d.ts +142 -0
- package/dist/relay/types.js +5 -0
- package/dist/relay/types.js.map +1 -0
- package/dist/rest/HttpClient.d.ts +80 -0
- package/dist/rest/HttpClient.js +148 -0
- package/dist/rest/HttpClient.js.map +1 -0
- package/dist/rest/RestError.d.ts +30 -0
- package/dist/rest/RestError.js +39 -0
- package/dist/rest/RestError.js.map +1 -0
- package/dist/rest/base/BaseResource.d.ts +24 -0
- package/dist/rest/base/BaseResource.js +29 -0
- package/dist/rest/base/BaseResource.js.map +1 -0
- package/dist/rest/base/CrudResource.d.ts +68 -0
- package/dist/rest/base/CrudResource.js +82 -0
- package/dist/rest/base/CrudResource.js.map +1 -0
- package/dist/rest/base/CrudWithAddresses.d.ts +22 -0
- package/dist/rest/base/CrudWithAddresses.js +25 -0
- package/dist/rest/base/CrudWithAddresses.js.map +1 -0
- package/{src/rest/index.ts → dist/rest/index.d.ts} +53 -122
- package/dist/rest/index.js +195 -0
- package/dist/rest/index.js.map +1 -0
- package/dist/rest/namespaces/addresses.d.ts +46 -0
- package/dist/rest/namespaces/addresses.js +55 -0
- package/dist/rest/namespaces/addresses.js.map +1 -0
- package/dist/rest/namespaces/calling.d.ts +382 -0
- package/dist/rest/namespaces/calling.js +478 -0
- package/dist/rest/namespaces/calling.js.map +1 -0
- package/dist/rest/namespaces/chat.d.ts +22 -0
- package/dist/rest/namespaces/chat.js +26 -0
- package/dist/rest/namespaces/chat.js.map +1 -0
- package/dist/rest/namespaces/compat.d.ts +585 -0
- package/dist/rest/namespaces/compat.js +735 -0
- package/dist/rest/namespaces/compat.js.map +1 -0
- package/dist/rest/namespaces/datasphere.d.ts +66 -0
- package/dist/rest/namespaces/datasphere.js +77 -0
- package/dist/rest/namespaces/datasphere.js.map +1 -0
- package/dist/rest/namespaces/fabric.d.ts +282 -0
- package/dist/rest/namespaces/fabric.js +373 -0
- package/dist/rest/namespaces/fabric.js.map +1 -0
- package/dist/rest/namespaces/imported-numbers.d.ts +22 -0
- package/dist/rest/namespaces/imported-numbers.js +26 -0
- package/dist/rest/namespaces/imported-numbers.js.map +1 -0
- package/dist/rest/namespaces/logs.d.ts +105 -0
- package/dist/rest/namespaces/logs.js +133 -0
- package/dist/rest/namespaces/logs.js.map +1 -0
- package/dist/rest/namespaces/lookup.d.ts +29 -0
- package/dist/rest/namespaces/lookup.js +32 -0
- package/dist/rest/namespaces/lookup.js.map +1 -0
- package/dist/rest/namespaces/mfa.d.ts +46 -0
- package/dist/rest/namespaces/mfa.js +54 -0
- package/dist/rest/namespaces/mfa.js.map +1 -0
- package/dist/rest/namespaces/number-groups.d.ts +49 -0
- package/dist/rest/namespaces/number-groups.js +58 -0
- package/dist/rest/namespaces/number-groups.js.map +1 -0
- package/dist/rest/namespaces/phone-numbers.d.ts +60 -0
- package/dist/rest/namespaces/phone-numbers.js +67 -0
- package/dist/rest/namespaces/phone-numbers.js.map +1 -0
- package/dist/rest/namespaces/project.d.ts +46 -0
- package/dist/rest/namespaces/project.js +56 -0
- package/dist/rest/namespaces/project.js.map +1 -0
- package/dist/rest/namespaces/pubsub.d.ts +22 -0
- package/dist/rest/namespaces/pubsub.js +26 -0
- package/dist/rest/namespaces/pubsub.js.map +1 -0
- package/dist/rest/namespaces/queues.d.ts +42 -0
- package/dist/rest/namespaces/queues.js +49 -0
- package/dist/rest/namespaces/queues.js.map +1 -0
- package/dist/rest/namespaces/recordings.d.ts +38 -0
- package/dist/rest/namespaces/recordings.js +45 -0
- package/dist/rest/namespaces/recordings.js.map +1 -0
- package/dist/rest/namespaces/registry.d.ts +141 -0
- package/dist/rest/namespaces/registry.js +178 -0
- package/dist/rest/namespaces/registry.js.map +1 -0
- package/dist/rest/namespaces/short-codes.d.ts +39 -0
- package/dist/rest/namespaces/short-codes.js +46 -0
- package/dist/rest/namespaces/short-codes.js.map +1 -0
- package/dist/rest/namespaces/sip-profile.d.ts +28 -0
- package/dist/rest/namespaces/sip-profile.js +34 -0
- package/dist/rest/namespaces/sip-profile.js.map +1 -0
- package/dist/rest/namespaces/verified-callers.d.ts +33 -0
- package/dist/rest/namespaces/verified-callers.js +39 -0
- package/dist/rest/namespaces/verified-callers.js.map +1 -0
- package/dist/rest/namespaces/video.d.ts +235 -0
- package/dist/rest/namespaces/video.js +297 -0
- package/dist/rest/namespaces/video.js.map +1 -0
- package/dist/rest/pagination.d.ts +39 -0
- package/dist/rest/pagination.js +78 -0
- package/dist/rest/pagination.js.map +1 -0
- package/dist/rest/types.d.ts +54 -0
- package/dist/rest/types.js +5 -0
- package/dist/rest/types.js.map +1 -0
- package/dist/skills/SkillBase.d.ts +404 -0
- package/dist/skills/SkillBase.js +471 -0
- package/dist/skills/SkillBase.js.map +1 -0
- package/dist/skills/SkillManager.d.ts +195 -0
- package/dist/skills/SkillManager.js +378 -0
- package/dist/skills/SkillManager.js.map +1 -0
- package/dist/skills/SkillRegistry.d.ts +176 -0
- package/dist/skills/SkillRegistry.js +310 -0
- package/dist/skills/SkillRegistry.js.map +1 -0
- package/dist/skills/builtin/api_ninjas_trivia.d.ts +47 -0
- package/dist/skills/builtin/api_ninjas_trivia.js +211 -0
- package/dist/skills/builtin/api_ninjas_trivia.js.map +1 -0
- package/dist/skills/builtin/ask_claude.d.ts +37 -0
- package/dist/skills/builtin/ask_claude.js +162 -0
- package/dist/skills/builtin/ask_claude.js.map +1 -0
- package/dist/skills/builtin/claude_skills.d.ts +75 -0
- package/dist/skills/builtin/claude_skills.js +753 -0
- package/dist/skills/builtin/claude_skills.js.map +1 -0
- package/dist/skills/builtin/custom_skills.d.ts +79 -0
- package/dist/skills/builtin/custom_skills.js +227 -0
- package/dist/skills/builtin/custom_skills.js.map +1 -0
- package/dist/skills/builtin/datasphere.d.ts +73 -0
- package/dist/skills/builtin/datasphere.js +350 -0
- package/dist/skills/builtin/datasphere.js.map +1 -0
- package/dist/skills/builtin/datasphere_serverless.d.ts +89 -0
- package/dist/skills/builtin/datasphere_serverless.js +291 -0
- package/dist/skills/builtin/datasphere_serverless.js.map +1 -0
- package/dist/skills/builtin/datetime.d.ts +40 -0
- package/dist/skills/builtin/datetime.js +118 -0
- package/dist/skills/builtin/datetime.js.map +1 -0
- package/dist/skills/builtin/google_maps.d.ts +48 -0
- package/dist/skills/builtin/google_maps.js +470 -0
- package/dist/skills/builtin/google_maps.js.map +1 -0
- package/dist/skills/builtin/index.d.ts +31 -0
- package/{src/skills/builtin/index.ts → dist/skills/builtin/index.js} +30 -36
- package/dist/skills/builtin/index.js.map +1 -0
- package/dist/skills/builtin/info_gatherer.d.ts +115 -0
- package/dist/skills/builtin/info_gatherer.js +328 -0
- package/dist/skills/builtin/info_gatherer.js.map +1 -0
- package/dist/skills/builtin/joke.d.ts +41 -0
- package/dist/skills/builtin/joke.js +156 -0
- package/dist/skills/builtin/joke.js.map +1 -0
- package/dist/skills/builtin/math.d.ts +39 -0
- package/dist/skills/builtin/math.js +119 -0
- package/dist/skills/builtin/math.js.map +1 -0
- package/dist/skills/builtin/mcp_gateway.d.ts +82 -0
- package/dist/skills/builtin/mcp_gateway.js +574 -0
- package/dist/skills/builtin/mcp_gateway.js.map +1 -0
- package/dist/skills/builtin/native_vector_search.d.ts +128 -0
- package/dist/skills/builtin/native_vector_search.js +752 -0
- package/dist/skills/builtin/native_vector_search.js.map +1 -0
- package/dist/skills/builtin/play_background_file.d.ts +59 -0
- package/dist/skills/builtin/play_background_file.js +274 -0
- package/dist/skills/builtin/play_background_file.js.map +1 -0
- package/dist/skills/builtin/spider.d.ts +91 -0
- package/dist/skills/builtin/spider.js +758 -0
- package/dist/skills/builtin/spider.js.map +1 -0
- package/dist/skills/builtin/swml_transfer.d.ts +66 -0
- package/dist/skills/builtin/swml_transfer.js +475 -0
- package/dist/skills/builtin/swml_transfer.js.map +1 -0
- package/dist/skills/builtin/weather_api.d.ts +59 -0
- package/dist/skills/builtin/weather_api.js +196 -0
- package/dist/skills/builtin/weather_api.js.map +1 -0
- package/dist/skills/builtin/web_search.d.ts +160 -0
- package/dist/skills/builtin/web_search.js +894 -0
- package/dist/skills/builtin/web_search.js.map +1 -0
- package/dist/skills/builtin/wikipedia_search.d.ts +77 -0
- package/dist/skills/builtin/wikipedia_search.js +241 -0
- package/dist/skills/builtin/wikipedia_search.js.map +1 -0
- package/{src/skills/index.ts → dist/skills/index.d.ts} +0 -1
- package/dist/skills/index.js +10 -0
- package/dist/skills/index.js.map +1 -0
- package/dist/types.d.ts +118 -0
- package/dist/types.js +5 -0
- package/dist/types.js.map +1 -0
- package/package.json +7 -1
- package/.github/workflows/publish.yml +0 -27
- package/.github/workflows/test.yml +0 -17
- package/CLAUDE.md +0 -112
- package/docs/MIGRATION-2.0.md +0 -81
- package/docs/agent-guide.md +0 -869
- package/docs/agent_guide.md +0 -1026
- package/docs/api-reference.md +0 -2420
- package/docs/api_reference.md +0 -1301
- package/docs/architecture.md +0 -843
- package/docs/cli-guide.md +0 -579
- package/docs/cli_guide.md +0 -448
- package/docs/cloud_functions_guide.md +0 -474
- package/docs/configuration.md +0 -422
- package/docs/contexts-guide.md +0 -787
- package/docs/contexts_guide.md +0 -511
- package/docs/datamap-guide.md +0 -1141
- package/docs/datamap_guide.md +0 -595
- package/docs/llm_parameters.md +0 -239
- package/docs/mcp_gateway_reference.md +0 -648
- package/docs/mcp_integration.md +0 -108
- package/docs/prefabs-guide.md +0 -800
- package/docs/sdk_features.md +0 -477
- package/docs/security.md +0 -436
- package/docs/serverless-guide.md +0 -513
- package/docs/skills-guide.md +0 -857
- package/docs/skills-system.md +0 -301
- package/docs/skills_parameter_schema.md +0 -392
- package/docs/skills_system.md +0 -467
- package/docs/swaig-reference.md +0 -1627
- package/docs/swaig_reference.md +0 -910
- package/docs/swml_service_guide.md +0 -600
- package/docs/third_party_skills.md +0 -533
- package/docs/web_service.md +0 -677
- package/examples/README.md +0 -131
- package/examples/advanced-datamap.ts +0 -100
- package/examples/advanced-dynamic-config.ts +0 -70
- package/examples/auto-vivified.ts +0 -94
- package/examples/call-flow.ts +0 -63
- package/examples/comprehensive-dynamic.ts +0 -125
- package/examples/contexts-steps.ts +0 -65
- package/examples/custom-path.ts +0 -45
- package/examples/datamap-tools.ts +0 -55
- package/examples/datasphere-multi-instance.ts +0 -63
- package/examples/datasphere-serverless-env.ts +0 -68
- package/examples/datasphere-webhook-env.ts +0 -66
- package/examples/datasphere.ts +0 -37
- package/examples/declarative.ts +0 -100
- package/examples/dynamic-config.ts +0 -54
- package/examples/dynamic-info-gatherer.ts +0 -69
- package/examples/dynamic-swml-service.ts +0 -67
- package/examples/gather-info.ts +0 -71
- package/examples/gather-per-question-functions-demo.ts +0 -140
- package/examples/joke-agent.ts +0 -34
- package/examples/kubernetes-agent.ts +0 -45
- package/examples/llm-params.ts +0 -69
- package/examples/mcp-agent.ts +0 -84
- package/examples/mcp-gateway.ts +0 -35
- package/examples/multi-agent.ts +0 -73
- package/examples/multi-endpoint.ts +0 -79
- package/examples/pom-prompt.ts +0 -71
- package/examples/prefab-concierge.ts +0 -47
- package/examples/prefab-faq.ts +0 -54
- package/examples/prefab-info-gatherer.ts +0 -33
- package/examples/prefab-receptionist.ts +0 -36
- package/examples/prefab-survey.ts +0 -68
- package/examples/record-call.ts +0 -67
- package/examples/relay-demo.ts +0 -33
- package/examples/room-and-sip.ts +0 -94
- package/examples/serverless-lambda.ts +0 -35
- package/examples/session-state.ts +0 -83
- package/examples/simple-agent.ts +0 -36
- package/examples/simple-static.ts +0 -29
- package/examples/skills-demo.ts +0 -38
- package/examples/step-function-inheritance-demo.ts +0 -124
- package/examples/swaig-features.ts +0 -187
- package/examples/swml-service-routing.ts +0 -66
- package/examples/swml-service.ts +0 -38
- package/examples/tap.ts +0 -68
- package/examples/verb-methods.ts +0 -45
- package/examples/web-search-multi-instance.ts +0 -72
- package/examples/web-search.ts +0 -38
- package/examples/wikipedia.ts +0 -36
- package/livewire/README.md +0 -140
- package/livewire/docs/migration-guide.md +0 -228
- package/livewire/examples/livewire-basic-agent.ts +0 -74
- package/livewire/examples/livewire-handoff.ts +0 -197
- package/livewire/examples/livewire-multi-tool.ts +0 -117
- package/relay/README.md +0 -70
- package/relay/RELAY_IMPLEMENTATION_GUIDE.md +0 -1257
- package/relay/docs/call-methods.md +0 -474
- package/relay/docs/client-reference.md +0 -142
- package/relay/docs/events.md +0 -134
- package/relay/docs/getting-started.md +0 -134
- package/relay/docs/guide.md +0 -306
- package/relay/docs/messaging.md +0 -182
- package/relay/examples/relay-inbound.ts +0 -66
- package/relay/examples/relay-messaging.ts +0 -71
- package/relay/examples/relay-outbound.ts +0 -76
- package/rest/README.md +0 -95
- package/rest/docs/calling.md +0 -273
- package/rest/docs/client-reference.md +0 -107
- package/rest/docs/compat.md +0 -204
- package/rest/docs/fabric.md +0 -183
- package/rest/docs/getting-started.md +0 -110
- package/rest/docs/guide.md +0 -351
- package/rest/docs/namespaces.md +0 -285
- package/rest/examples/rest-10dlc-registration.ts +0 -161
- package/rest/examples/rest-calling-ivr-and-ai.ts +0 -102
- package/rest/examples/rest-calling-play-and-record.ts +0 -91
- package/rest/examples/rest-client.ts +0 -65
- package/rest/examples/rest-compat-laml.ts +0 -210
- package/rest/examples/rest-datasphere-search.ts +0 -82
- package/rest/examples/rest-fabric-conferences-and-routing.ts +0 -144
- package/rest/examples/rest-fabric-subscribers-and-sip.ts +0 -108
- package/rest/examples/rest-fabric-swml-and-callflows.ts +0 -99
- package/rest/examples/rest-manage-resources.ts +0 -65
- package/rest/examples/rest-phone-number-management.ts +0 -197
- package/rest/examples/rest-queues-mfa-and-recordings.ts +0 -143
- package/rest/examples/rest-video-rooms.ts +0 -186
- package/src/AgentBase.ts +0 -2489
- package/src/AgentServer.ts +0 -415
- package/src/AuthHandler.ts +0 -256
- package/src/ConfigLoader.ts +0 -447
- package/src/ContextBuilder.ts +0 -1150
- package/src/DataMap.ts +0 -449
- package/src/FunctionResult.ts +0 -866
- package/src/Logger.ts +0 -337
- package/src/PomBuilder.ts +0 -439
- package/src/PromptManager.ts +0 -133
- package/src/SWMLHandler.ts +0 -298
- package/src/SWMLService.ts +0 -717
- package/src/SchemaUtils.ts +0 -361
- package/src/ServerlessAdapter.ts +0 -221
- package/src/SessionManager.ts +0 -311
- package/src/SslConfig.ts +0 -118
- package/src/SwaigFunction.ts +0 -276
- package/src/SwmlBuilder.ts +0 -258
- package/src/SwmlVerbMethods.generated.ts +0 -234
- package/src/TypeInference.ts +0 -181
- package/src/WebService.ts +0 -619
- package/src/cli/agent-loader.ts +0 -166
- package/src/cli/mock-data.ts +0 -111
- package/src/cli/swaig-test.ts +0 -452
- package/src/generateVerbTypes.ts +0 -322
- package/src/index.ts +0 -167
- package/src/livewire/index.ts +0 -950
- package/src/prefabs/ConciergeAgent.ts +0 -287
- package/src/prefabs/FAQBotAgent.ts +0 -384
- package/src/prefabs/InfoGathererAgent.ts +0 -339
- package/src/prefabs/ReceptionistAgent.ts +0 -366
- package/src/prefabs/SurveyAgent.ts +0 -646
- package/src/relay/Action.ts +0 -314
- package/src/relay/Call.ts +0 -854
- package/src/relay/Deferred.ts +0 -71
- package/src/relay/Message.ts +0 -148
- package/src/relay/RelayClient.ts +0 -1036
- package/src/relay/RelayError.ts +0 -14
- package/src/relay/RelayEvent.ts +0 -892
- package/src/relay/index.ts +0 -123
- package/src/relay/types.ts +0 -149
- package/src/rest/HttpClient.ts +0 -103
- package/src/rest/RestError.ts +0 -31
- package/src/rest/base/BaseResource.ts +0 -19
- package/src/rest/base/CrudResource.ts +0 -51
- package/src/rest/base/CrudWithAddresses.ts +0 -26
- package/src/rest/namespaces/addresses.ts +0 -32
- package/src/rest/namespaces/calling.ts +0 -187
- package/src/rest/namespaces/chat.ts +0 -20
- package/src/rest/namespaces/compat.ts +0 -352
- package/src/rest/namespaces/datasphere.ts +0 -45
- package/src/rest/namespaces/fabric.ts +0 -222
- package/src/rest/namespaces/imported-numbers.ts +0 -20
- package/src/rest/namespaces/logs.ts +0 -84
- package/src/rest/namespaces/lookup.ts +0 -21
- package/src/rest/namespaces/mfa.ts +0 -30
- package/src/rest/namespaces/number-groups.ts +0 -38
- package/src/rest/namespaces/phone-numbers.ts +0 -44
- package/src/rest/namespaces/project.ts +0 -36
- package/src/rest/namespaces/pubsub.ts +0 -20
- package/src/rest/namespaces/queues.ts +0 -33
- package/src/rest/namespaces/recordings.ts +0 -28
- package/src/rest/namespaces/registry.ts +0 -101
- package/src/rest/namespaces/short-codes.ts +0 -28
- package/src/rest/namespaces/sip-profile.ts +0 -25
- package/src/rest/namespaces/verified-callers.ts +0 -27
- package/src/rest/namespaces/video.ts +0 -165
- package/src/rest/pagination.ts +0 -84
- package/src/rest/types.ts +0 -61
- package/src/skills/SkillBase.ts +0 -547
- package/src/skills/SkillManager.ts +0 -415
- package/src/skills/SkillRegistry.ts +0 -367
- package/src/skills/builtin/api_ninjas_trivia.ts +0 -280
- package/src/skills/builtin/ask_claude.ts +0 -241
- package/src/skills/builtin/claude_skills.ts +0 -978
- package/src/skills/builtin/custom_skills.ts +0 -312
- package/src/skills/builtin/datasphere.ts +0 -438
- package/src/skills/builtin/datasphere_serverless.ts +0 -339
- package/src/skills/builtin/datetime.ts +0 -130
- package/src/skills/builtin/google_maps.ts +0 -651
- package/src/skills/builtin/info_gatherer.ts +0 -405
- package/src/skills/builtin/joke.ts +0 -191
- package/src/skills/builtin/math.ts +0 -142
- package/src/skills/builtin/mcp_gateway.ts +0 -677
- package/src/skills/builtin/native_vector_search.ts +0 -901
- package/src/skills/builtin/play_background_file.ts +0 -358
- package/src/skills/builtin/spider.ts +0 -869
- package/src/skills/builtin/swml_transfer.ts +0 -635
- package/src/skills/builtin/weather_api.ts +0 -248
- package/src/skills/builtin/web_search.ts +0 -1074
- package/src/skills/builtin/wikipedia_search.ts +0 -299
- package/src/types.ts +0 -132
- package/tests/AgentBase.test.ts +0 -1093
- package/tests/AgentServer.test.ts +0 -126
- package/tests/AuthHandler.test.ts +0 -133
- package/tests/ConfigLoader.test.ts +0 -151
- package/tests/ContextBuilder.test.ts +0 -108
- package/tests/DataMap.test.ts +0 -367
- package/tests/EphemeralSkillCopy.test.ts +0 -107
- package/tests/FunctionResult.test.ts +0 -298
- package/tests/GracefulShutdown.test.ts +0 -46
- package/tests/Logger.test.ts +0 -420
- package/tests/PomBuilder.test.ts +0 -228
- package/tests/ProxyDetection.test.ts +0 -228
- package/tests/SWMLService.test.ts +0 -320
- package/tests/SWMLVerbHandler.test.ts +0 -523
- package/tests/SchemaUtils.test.ts +0 -106
- package/tests/SchemaUtils.verb.test.ts +0 -206
- package/tests/SecurityUtils.test.ts +0 -192
- package/tests/ServerlessAdapter.test.ts +0 -222
- package/tests/SessionManager.test.ts +0 -257
- package/tests/SkillBaseFeatures.test.ts +0 -130
- package/tests/SkillMultiInstance.test.ts +0 -102
- package/tests/SkillParameterSchemas.test.ts +0 -134
- package/tests/SkillRegistrySchema.test.ts +0 -84
- package/tests/SslConfig.test.ts +0 -97
- package/tests/SwmlBuilder.test.ts +0 -400
- package/tests/TypeInference.test.ts +0 -165
- package/tests/VerbHandlerRegistry.test.ts +0 -128
- package/tests/cli/mock-data.test.ts +0 -113
- package/tests/cli/swaig-test.test.ts +0 -108
- package/tests/examples.test.ts +0 -194
- package/tests/fixtures/scrape-parity/README.md +0 -53
- package/tests/fixtures/scrape-parity/expected/01_simple_article.json +0 -5
- package/tests/fixtures/scrape-parity/expected/02_class_based_noise.json +0 -5
- package/tests/fixtures/scrape-parity/expected/03_nested_containers.json +0 -5
- package/tests/fixtures/scrape-parity/expected/04_bare_body.json +0 -5
- package/tests/fixtures/scrape-parity/expected/05_malformed.json +0 -5
- package/tests/fixtures/scrape-parity/expected/06_multi_class.json +0 -5
- package/tests/fixtures/scrape-parity/expected/07_anchor_pattern.json +0 -5
- package/tests/fixtures/scrape-parity/expected/08_inline_script.json +0 -5
- package/tests/fixtures/scrape-parity/expected/09_whitespace_nbsp.json +0 -5
- package/tests/fixtures/scrape-parity/expected/10_entity_unicode.json +0 -5
- package/tests/fixtures/scrape-parity/expected/11_cdata_comments.json +0 -5
- package/tests/fixtures/scrape-parity/expected/12_deep_nested_removals.json +0 -5
- package/tests/fixtures/scrape-parity/html/01_simple_article.html +0 -18
- package/tests/fixtures/scrape-parity/html/02_class_based_noise.html +0 -18
- package/tests/fixtures/scrape-parity/html/03_nested_containers.html +0 -13
- package/tests/fixtures/scrape-parity/html/04_bare_body.html +0 -9
- package/tests/fixtures/scrape-parity/html/05_malformed.html +0 -11
- package/tests/fixtures/scrape-parity/html/06_multi_class.html +0 -18
- package/tests/fixtures/scrape-parity/html/07_anchor_pattern.html +0 -12
- package/tests/fixtures/scrape-parity/html/08_inline_script.html +0 -17
- package/tests/fixtures/scrape-parity/html/09_whitespace_nbsp.html +0 -21
- package/tests/fixtures/scrape-parity/html/10_entity_unicode.html +0 -10
- package/tests/fixtures/scrape-parity/html/11_cdata_comments.html +0 -13
- package/tests/fixtures/scrape-parity/html/12_deep_nested_removals.html +0 -24
- package/tests/fixtures/scrape-parity/python_extract.py +0 -109
- package/tests/livewire/livewire.test.ts +0 -780
- package/tests/mcp.test.ts +0 -221
- package/tests/prefabs/prefabs.test.ts +0 -1093
- package/tests/relay/Action.test.ts +0 -392
- package/tests/relay/Call.test.ts +0 -535
- package/tests/relay/Deferred.test.ts +0 -71
- package/tests/relay/Message.test.ts +0 -164
- package/tests/relay/RelayClient.test.ts +0 -779
- package/tests/relay/RelayEvent.test.ts +0 -463
- package/tests/relay/helpers.ts +0 -79
- package/tests/rest/HttpClient.test.ts +0 -274
- package/tests/rest/RestError.test.ts +0 -53
- package/tests/rest/calling.test.ts +0 -156
- package/tests/rest/client.test.ts +0 -197
- package/tests/rest/compat.test.ts +0 -335
- package/tests/rest/datasphere.test.ts +0 -71
- package/tests/rest/fabric.test.ts +0 -186
- package/tests/rest/helpers.ts +0 -95
- package/tests/rest/logs.test.ts +0 -68
- package/tests/rest/pagination.test.ts +0 -133
- package/tests/rest/registry.test.ts +0 -94
- package/tests/rest/relay-rest.test.ts +0 -290
- package/tests/rest/video.test.ts +0 -173
- package/tests/setup.ts +0 -6
- package/tests/skills/SkillBase.test.ts +0 -108
- package/tests/skills/SkillManager.test.ts +0 -268
- package/tests/skills/SkillRegistry.test.ts +0 -176
- package/tests/skills/builtin.test.ts +0 -1472
- package/tests/skills/claude-skills.test.ts +0 -54
- package/tests/skills/custom-skills.test.ts +0 -53
- package/tests/skills/datasphere-serverless.test.ts +0 -70
- package/tests/skills/datasphere.test.ts +0 -107
- package/tests/skills/datetime.test.ts +0 -101
- package/tests/skills/google-maps.test.ts +0 -78
- package/tests/skills/info-gatherer.test.ts +0 -411
- package/tests/skills/joke.test.ts +0 -81
- package/tests/skills/math.test.ts +0 -68
- package/tests/skills/mcp-gateway.test.ts +0 -101
- package/tests/skills/play-background.test.ts +0 -54
- package/tests/skills/spider.test.ts +0 -108
- package/tests/skills/swml-transfer.test.ts +0 -178
- package/tests/skills/trivia.test.ts +0 -54
- package/tests/skills/vector-search.test.ts +0 -135
- package/tests/skills/weather-api.test.ts +0 -77
- package/tests/skills/web-search-parity.test.ts +0 -59
- package/tests/skills/web-search.test.ts +0 -103
- package/tests/skills/wikipedia.test.ts +0 -63
- package/tsconfig.json +0 -18
- package/vitest.config.ts +0 -9
- /package/{src → dist}/schema.json +0 -0
|
@@ -0,0 +1,894 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Web Search Skill - Searches the web using the Google Custom Search API.
|
|
3
|
+
*
|
|
4
|
+
* Tier 3 built-in skill: requires `GOOGLE_SEARCH_API_KEY` and
|
|
5
|
+
* `GOOGLE_SEARCH_ENGINE_ID` (legacy alias: `GOOGLE_SEARCH_CX`) environment
|
|
6
|
+
* variables, or the equivalent config params. Uses the Google Custom Search
|
|
7
|
+
* JSON API to perform web searches and return formatted results.
|
|
8
|
+
*/
|
|
9
|
+
import { SkillBase } from '../SkillBase.js';
|
|
10
|
+
import { FunctionResult } from '../../FunctionResult.js';
|
|
11
|
+
import { MAX_SKILL_INPUT_LENGTH, validateUrl } from '../../SecurityUtils.js';
|
|
12
|
+
import { getLogger } from '../../Logger.js';
|
|
13
|
+
import * as cheerio from 'cheerio';
|
|
14
|
+
const log = getLogger('WebSearchSkill');
|
|
15
|
+
const DEFAULT_NO_RESULTS_MESSAGE = "I couldn't find quality results for '{query}'. " +
|
|
16
|
+
'The search returned only low-quality or inaccessible pages. ' +
|
|
17
|
+
'Try rephrasing your search or asking about a different topic.';
|
|
18
|
+
/** Selector priority — Python skill.py:220-228. */
|
|
19
|
+
const CONTENT_CANDIDATES = [
|
|
20
|
+
'article',
|
|
21
|
+
'main',
|
|
22
|
+
'[role="main"]',
|
|
23
|
+
'.content',
|
|
24
|
+
'#content',
|
|
25
|
+
'.post',
|
|
26
|
+
'.entry-content',
|
|
27
|
+
'.article-body',
|
|
28
|
+
'.story-body',
|
|
29
|
+
'.markdown-body',
|
|
30
|
+
'.wiki-body',
|
|
31
|
+
'.documentation',
|
|
32
|
+
];
|
|
33
|
+
/** Structural tags removed from the picked subtree — Python skill.py:239. */
|
|
34
|
+
const UNWANTED_TAGS = [
|
|
35
|
+
'script',
|
|
36
|
+
'style',
|
|
37
|
+
'nav',
|
|
38
|
+
'header',
|
|
39
|
+
'footer',
|
|
40
|
+
'aside',
|
|
41
|
+
'noscript',
|
|
42
|
+
'iframe',
|
|
43
|
+
];
|
|
44
|
+
/** Class/id name patterns removed from the picked subtree — Python skill.py:245-257. */
|
|
45
|
+
const UNWANTED_PATTERNS = [
|
|
46
|
+
'sidebar',
|
|
47
|
+
'navigation',
|
|
48
|
+
'menu',
|
|
49
|
+
'advertisement',
|
|
50
|
+
'ads',
|
|
51
|
+
'banner',
|
|
52
|
+
'popup',
|
|
53
|
+
'modal',
|
|
54
|
+
'cookie',
|
|
55
|
+
'gdpr',
|
|
56
|
+
'subscribe',
|
|
57
|
+
'newsletter',
|
|
58
|
+
'comments',
|
|
59
|
+
'related',
|
|
60
|
+
'share',
|
|
61
|
+
'social',
|
|
62
|
+
];
|
|
63
|
+
/**
|
|
64
|
+
* Run the HTML → plain-text extraction pipeline that mirrors Python's
|
|
65
|
+
* `GoogleSearchScraper.extract_html_content` (skill.py:204-282).
|
|
66
|
+
*
|
|
67
|
+
* Pipeline:
|
|
68
|
+
* 1. Pre-process `<![CDATA[…]]>` sections to plain text (Python html.parser
|
|
69
|
+
* keeps CDATA content; cheerio/htmlparser2 drops it).
|
|
70
|
+
* 2. Walk {@link CONTENT_CANDIDATES} in order, picking the first match.
|
|
71
|
+
* Fall back to `<body>` or the raw document.
|
|
72
|
+
* 3. Clone the picked subtree so tag/pattern removal only affects it —
|
|
73
|
+
* analogous to Python's `content_soup = BeautifulSoup(str(main_content))`.
|
|
74
|
+
* The selector-first-then-filter order is load-bearing: if the real
|
|
75
|
+
* content is wrapped in a sidebar-pattern div, Python still finds it
|
|
76
|
+
* because the selector runs before removal.
|
|
77
|
+
* 4. Remove {@link UNWANTED_TAGS} and every element matching any of
|
|
78
|
+
* {@link UNWANTED_PATTERNS} on either `class` or `id` (case-insensitive).
|
|
79
|
+
* 5. Collapse whitespace and trim.
|
|
80
|
+
*
|
|
81
|
+
* Exported so `tests/skills/web-search-parity.test.ts` can verify byte-
|
|
82
|
+
* identical behavior against Python BeautifulSoup fixtures; not re-exported
|
|
83
|
+
* from the skills barrel, so this stays internal to the skill module.
|
|
84
|
+
*
|
|
85
|
+
* @internal
|
|
86
|
+
*/
|
|
87
|
+
export function extractTextFromHtml(html) {
|
|
88
|
+
const normalized = html.replace(/<!\[CDATA\[([\s\S]*?)\]\]>/g, (_, content) => content);
|
|
89
|
+
const $ = cheerio.load(normalized);
|
|
90
|
+
let pickedHtml = '';
|
|
91
|
+
for (const sel of CONTENT_CANDIDATES) {
|
|
92
|
+
const picked = $(sel).first();
|
|
93
|
+
if (picked.length > 0) {
|
|
94
|
+
pickedHtml = $.html(picked);
|
|
95
|
+
break;
|
|
96
|
+
}
|
|
97
|
+
}
|
|
98
|
+
if (!pickedHtml) {
|
|
99
|
+
const bodyEl = $('body').first();
|
|
100
|
+
pickedHtml = bodyEl.length > 0 ? $.html(bodyEl) : normalized;
|
|
101
|
+
}
|
|
102
|
+
const $sub = cheerio.load(pickedHtml);
|
|
103
|
+
for (const tag of UNWANTED_TAGS) {
|
|
104
|
+
$sub(tag).remove();
|
|
105
|
+
}
|
|
106
|
+
for (const pattern of UNWANTED_PATTERNS) {
|
|
107
|
+
const regex = new RegExp(pattern, 'i');
|
|
108
|
+
$sub('[class]').each((_, el) => {
|
|
109
|
+
const cls = $sub(el).attr('class') ?? '';
|
|
110
|
+
if (regex.test(cls))
|
|
111
|
+
$sub(el).remove();
|
|
112
|
+
});
|
|
113
|
+
$sub('[id]').each((_, el) => {
|
|
114
|
+
const id = $sub(el).attr('id') ?? '';
|
|
115
|
+
if (regex.test(id))
|
|
116
|
+
$sub(el).remove();
|
|
117
|
+
});
|
|
118
|
+
}
|
|
119
|
+
return $sub.root().text().replace(/\s+/g, ' ').trim();
|
|
120
|
+
}
|
|
121
|
+
/**
|
|
122
|
+
* Searches the web using the Google Custom Search JSON API.
|
|
123
|
+
*
|
|
124
|
+
* Tier 3 built-in skill. Credentials can be supplied via the `api_key` and
|
|
125
|
+
* `search_engine_id` params or `GOOGLE_SEARCH_API_KEY` /
|
|
126
|
+
* `GOOGLE_SEARCH_ENGINE_ID` (legacy: `GOOGLE_SEARCH_CX`) environment variables.
|
|
127
|
+
*
|
|
128
|
+
* The handler mirrors Python's `search_and_scrape_best` pipeline: fetches
|
|
129
|
+
* `oversample_factor × num_results` candidates from Google, scrapes each
|
|
130
|
+
* result page (SSRF-guarded, cheerio-based text extraction), scores for
|
|
131
|
+
* quality (length + query relevance + boilerplate penalty), deduplicates by
|
|
132
|
+
* domain, and returns the top `num_results` above `min_quality_score` with
|
|
133
|
+
* full page content. If every scrape fails or falls below the threshold the
|
|
134
|
+
* handler falls back to raw API snippets so the agent still has something
|
|
135
|
+
* to say.
|
|
136
|
+
*
|
|
137
|
+
* Supported config: `tool_name`, `num_results`, `no_results_message`,
|
|
138
|
+
* `safe_search`, `delay`, `max_content_length`, `oversample_factor`,
|
|
139
|
+
* `min_quality_score`.
|
|
140
|
+
*
|
|
141
|
+
* @example
|
|
142
|
+
* ```ts
|
|
143
|
+
* agent.addSkill('web_search', {
|
|
144
|
+
* api_key: process.env.GOOGLE_SEARCH_API_KEY,
|
|
145
|
+
* search_engine_id: process.env.GOOGLE_CSE_ID,
|
|
146
|
+
* num_results: 3,
|
|
147
|
+
* });
|
|
148
|
+
* ```
|
|
149
|
+
*/
|
|
150
|
+
export class WebSearchSkill extends SkillBase {
|
|
151
|
+
// Python ground truth: skills/web_search/skill.py:559-567
|
|
152
|
+
// REQUIRED_PACKAGES = ["bs4", "requests"] in Python; TS uses cheerio + fetch so [].
|
|
153
|
+
static SKILL_NAME = 'web_search';
|
|
154
|
+
static SKILL_DESCRIPTION = 'Search the web for information using Google Custom Search API';
|
|
155
|
+
static SKILL_VERSION = '2.0.0';
|
|
156
|
+
static REQUIRED_PACKAGES = [];
|
|
157
|
+
static REQUIRED_ENV_VARS = [];
|
|
158
|
+
static SUPPORTS_MULTIPLE_INSTANCES = true;
|
|
159
|
+
static getParameterSchema() {
|
|
160
|
+
return {
|
|
161
|
+
...super.getParameterSchema(),
|
|
162
|
+
api_key: {
|
|
163
|
+
type: 'string',
|
|
164
|
+
description: 'Google Custom Search API key',
|
|
165
|
+
required: true,
|
|
166
|
+
hidden: true,
|
|
167
|
+
env_var: 'GOOGLE_SEARCH_API_KEY',
|
|
168
|
+
},
|
|
169
|
+
search_engine_id: {
|
|
170
|
+
type: 'string',
|
|
171
|
+
description: 'Google Custom Search Engine ID',
|
|
172
|
+
required: true,
|
|
173
|
+
hidden: true,
|
|
174
|
+
env_var: 'GOOGLE_SEARCH_ENGINE_ID',
|
|
175
|
+
},
|
|
176
|
+
tool_name: {
|
|
177
|
+
type: 'string',
|
|
178
|
+
description: 'Custom tool name for this Web Search instance.',
|
|
179
|
+
required: false,
|
|
180
|
+
},
|
|
181
|
+
num_results: {
|
|
182
|
+
type: 'integer',
|
|
183
|
+
description: 'Number of high-quality results to return',
|
|
184
|
+
default: 3,
|
|
185
|
+
required: false,
|
|
186
|
+
min: 1,
|
|
187
|
+
max: 10,
|
|
188
|
+
},
|
|
189
|
+
delay: {
|
|
190
|
+
type: 'number',
|
|
191
|
+
description: 'Delay between scraping pages in seconds',
|
|
192
|
+
default: 0.5,
|
|
193
|
+
required: false,
|
|
194
|
+
min: 0,
|
|
195
|
+
},
|
|
196
|
+
max_content_length: {
|
|
197
|
+
type: 'integer',
|
|
198
|
+
description: 'Maximum total response size in characters',
|
|
199
|
+
default: 32768,
|
|
200
|
+
required: false,
|
|
201
|
+
min: 1000,
|
|
202
|
+
},
|
|
203
|
+
oversample_factor: {
|
|
204
|
+
type: 'number',
|
|
205
|
+
description: 'How many extra results to fetch for quality filtering (e.g., 2.5 = fetch 2.5x requested)',
|
|
206
|
+
default: 2.5,
|
|
207
|
+
required: false,
|
|
208
|
+
min: 1.0,
|
|
209
|
+
max: 3.5,
|
|
210
|
+
},
|
|
211
|
+
min_quality_score: {
|
|
212
|
+
type: 'number',
|
|
213
|
+
description: 'Minimum quality score (0-1) for including a result',
|
|
214
|
+
default: 0.3,
|
|
215
|
+
required: false,
|
|
216
|
+
min: 0,
|
|
217
|
+
max: 1,
|
|
218
|
+
},
|
|
219
|
+
no_results_message: {
|
|
220
|
+
type: 'string',
|
|
221
|
+
description: 'Message to show when no quality results are found. Use {query} as placeholder.',
|
|
222
|
+
default: DEFAULT_NO_RESULTS_MESSAGE,
|
|
223
|
+
required: false,
|
|
224
|
+
},
|
|
225
|
+
safe_search: {
|
|
226
|
+
type: 'string',
|
|
227
|
+
description: 'Safe search level.',
|
|
228
|
+
default: 'medium',
|
|
229
|
+
enum: ['off', 'medium', 'high'],
|
|
230
|
+
},
|
|
231
|
+
};
|
|
232
|
+
}
|
|
233
|
+
/**
|
|
234
|
+
* @returns Manifest declaring Google Search credentials as required env vars.
|
|
235
|
+
* Reports `GOOGLE_SEARCH_ENGINE_ID` as the canonical name; `GOOGLE_SEARCH_CX`
|
|
236
|
+
* is still accepted as a legacy fallback at runtime.
|
|
237
|
+
*/
|
|
238
|
+
/**
|
|
239
|
+
* Validate required credentials before the skill becomes active.
|
|
240
|
+
*
|
|
241
|
+
* Mirrors Python's `setup()` (skill.py:559-600) which checks `api_key` and
|
|
242
|
+
* `search_engine_id` and returns `False` (logging an error) if either is
|
|
243
|
+
* absent. In the TS SDK credentials may also arrive via environment variables
|
|
244
|
+
* (`GOOGLE_SEARCH_API_KEY` / `GOOGLE_SEARCH_ENGINE_ID` or the legacy alias
|
|
245
|
+
* `GOOGLE_SEARCH_CX`), so both config params and env vars are checked.
|
|
246
|
+
* @returns `true` if all required credentials are present, `false` otherwise.
|
|
247
|
+
*/
|
|
248
|
+
async setup() {
|
|
249
|
+
const apiKey = this.getConfig('api_key', undefined) ??
|
|
250
|
+
process.env['GOOGLE_SEARCH_API_KEY'];
|
|
251
|
+
const searchEngineId = this.getConfig('search_engine_id', undefined) ??
|
|
252
|
+
process.env['GOOGLE_SEARCH_ENGINE_ID'] ??
|
|
253
|
+
process.env['GOOGLE_SEARCH_CX'];
|
|
254
|
+
const missing = [];
|
|
255
|
+
if (!apiKey)
|
|
256
|
+
missing.push('api_key / GOOGLE_SEARCH_API_KEY');
|
|
257
|
+
if (!searchEngineId)
|
|
258
|
+
missing.push('search_engine_id / GOOGLE_SEARCH_ENGINE_ID');
|
|
259
|
+
if (missing.length > 0) {
|
|
260
|
+
log.error('web_search: missing required parameters', { missing });
|
|
261
|
+
return false;
|
|
262
|
+
}
|
|
263
|
+
return true;
|
|
264
|
+
}
|
|
265
|
+
/**
|
|
266
|
+
* Instance key for the SkillManager. Includes the configured
|
|
267
|
+
* `search_engine_id` (or `"default"`) and `tool_name` (or `"web_search"`)
|
|
268
|
+
* to match Python's `"{SKILL_NAME}_{search_engine_id}_{tool_name}"` scheme.
|
|
269
|
+
*/
|
|
270
|
+
getInstanceKey() {
|
|
271
|
+
const searchEngineId = this.getConfig('search_engine_id', '') || 'default';
|
|
272
|
+
const toolName = this.getConfig('tool_name', this.skillName);
|
|
273
|
+
return `${this.skillName}_${searchEngineId}_${toolName}`;
|
|
274
|
+
}
|
|
275
|
+
/** Global data injected into the agent's SWML context (mirrors Python). */
|
|
276
|
+
getGlobalData() {
|
|
277
|
+
return {
|
|
278
|
+
web_search_enabled: true,
|
|
279
|
+
search_provider: 'Google Custom Search',
|
|
280
|
+
quality_filtering: true,
|
|
281
|
+
};
|
|
282
|
+
}
|
|
283
|
+
/** Resolve the tool name (defaults to `web_search`, matches Python default). */
|
|
284
|
+
getToolName() {
|
|
285
|
+
return this.getConfig('tool_name', 'web_search');
|
|
286
|
+
}
|
|
287
|
+
/**
|
|
288
|
+
* @returns A single tool (named via `tool_name`) that performs a Google
|
|
289
|
+
* Custom Search and returns formatted results.
|
|
290
|
+
*/
|
|
291
|
+
getTools() {
|
|
292
|
+
const configNumResults = this.getConfig('num_results', 3);
|
|
293
|
+
const safeSearch = this.getConfig('safe_search', 'medium');
|
|
294
|
+
const oversampleFactor = this.getConfig('oversample_factor', 2.5);
|
|
295
|
+
const minQualityScore = this.getConfig('min_quality_score', 0.3);
|
|
296
|
+
const maxContentLength = this.getConfig('max_content_length', 32768);
|
|
297
|
+
const delaySeconds = this.getConfig('delay', 0.5);
|
|
298
|
+
const noResultsMessage = this.getConfig('no_results_message', DEFAULT_NO_RESULTS_MESSAGE);
|
|
299
|
+
const toolName = this.getToolName();
|
|
300
|
+
return [
|
|
301
|
+
{
|
|
302
|
+
name: toolName,
|
|
303
|
+
description: 'Search the web for high-quality information, automatically filtering low-quality results',
|
|
304
|
+
parameters: {
|
|
305
|
+
query: {
|
|
306
|
+
type: 'string',
|
|
307
|
+
description: "The search query - what you want to find information about",
|
|
308
|
+
},
|
|
309
|
+
},
|
|
310
|
+
required: ['query'],
|
|
311
|
+
handler: async (args, _rawData) => {
|
|
312
|
+
const rawQuery = args['query'];
|
|
313
|
+
if (!rawQuery ||
|
|
314
|
+
typeof rawQuery !== 'string' ||
|
|
315
|
+
rawQuery.trim().length === 0) {
|
|
316
|
+
return new FunctionResult('Please provide a search query. What would you like me to search for?');
|
|
317
|
+
}
|
|
318
|
+
const query = rawQuery.trim();
|
|
319
|
+
if (query.length > MAX_SKILL_INPUT_LENGTH) {
|
|
320
|
+
return new FunctionResult('Search query is too long.');
|
|
321
|
+
}
|
|
322
|
+
const apiKey = this.getConfig('api_key', undefined) ??
|
|
323
|
+
process.env['GOOGLE_SEARCH_API_KEY'];
|
|
324
|
+
const searchEngineId = this.getConfig('search_engine_id', undefined) ??
|
|
325
|
+
process.env['GOOGLE_SEARCH_ENGINE_ID'] ??
|
|
326
|
+
process.env['GOOGLE_SEARCH_CX'];
|
|
327
|
+
if (!apiKey || !searchEngineId) {
|
|
328
|
+
return new FunctionResult('Service is not configured. Please contact your administrator.');
|
|
329
|
+
}
|
|
330
|
+
const count = Math.max(1, Math.min(10, configNumResults));
|
|
331
|
+
// Python skill.py:433 — `fetch_count = min(10, int(num_results * oversample_factor))`.
|
|
332
|
+
// Python's `int()` truncates toward zero; for positive values that's
|
|
333
|
+
// equivalent to Math.floor. Do NOT add a `max(count, …)` floor —
|
|
334
|
+
// Python's fetch_count can be less than num_results (e.g. factor=0.5).
|
|
335
|
+
const fetchCount = Math.min(10, Math.floor(count * oversampleFactor));
|
|
336
|
+
try {
|
|
337
|
+
const encodedQuery = encodeURIComponent(query);
|
|
338
|
+
const safeParam = safeSearch !== 'off' ? `&safe=${safeSearch}` : '';
|
|
339
|
+
const url = `https://www.googleapis.com/customsearch/v1` +
|
|
340
|
+
// Python uses timeout=15 on the API request (skill.py:220).
|
|
341
|
+
`?key=${apiKey}&cx=${searchEngineId}&q=${encodedQuery}&num=${fetchCount}${safeParam}`;
|
|
342
|
+
const controller = new AbortController();
|
|
343
|
+
const timeout = setTimeout(() => controller.abort(), 15_000);
|
|
344
|
+
let response;
|
|
345
|
+
try {
|
|
346
|
+
response = await fetch(url, { signal: controller.signal });
|
|
347
|
+
}
|
|
348
|
+
finally {
|
|
349
|
+
clearTimeout(timeout);
|
|
350
|
+
}
|
|
351
|
+
const data = (await response.json());
|
|
352
|
+
if (data.error) {
|
|
353
|
+
log.error('web_search_api_error', { code: data.error.code });
|
|
354
|
+
return new FunctionResult('The web search service encountered an error. Please try again later.');
|
|
355
|
+
}
|
|
356
|
+
if (!data.items || data.items.length === 0) {
|
|
357
|
+
return new FunctionResult(WebSearchSkill._formatNoResultsMessage(noResultsMessage, query));
|
|
358
|
+
}
|
|
359
|
+
const allCandidates = [];
|
|
360
|
+
for (let idx = 0; idx < data.items.length; idx++) {
|
|
361
|
+
const item = data.items[idx];
|
|
362
|
+
try {
|
|
363
|
+
// SSRF / URL sanity — Python has no explicit pre-check; the
|
|
364
|
+
// scraper's inner `validate_url` handles it. We pre-parse to
|
|
365
|
+
// derive `host` for the domain-diverse selection pass.
|
|
366
|
+
const host = new URL(item.link).host;
|
|
367
|
+
const result = await this._scrapeUrl(item.link, maxContentLength, 10_000, query);
|
|
368
|
+
if (result !== null && result.score >= minQualityScore) {
|
|
369
|
+
allCandidates.push({
|
|
370
|
+
item,
|
|
371
|
+
text: result.text,
|
|
372
|
+
score: result.score,
|
|
373
|
+
host,
|
|
374
|
+
text_length: result.text_length,
|
|
375
|
+
sentence_count: result.sentence_count,
|
|
376
|
+
query_relevance: result.query_relevance,
|
|
377
|
+
query_words_found: result.query_words_found,
|
|
378
|
+
domain: result.domain,
|
|
379
|
+
});
|
|
380
|
+
}
|
|
381
|
+
}
|
|
382
|
+
catch {
|
|
383
|
+
// URL parse failure — skip this result but still apply the
|
|
384
|
+
// inter-request delay below so cadence matches Python.
|
|
385
|
+
}
|
|
386
|
+
// Python skill.py:461-463 sleeps `delay` seconds between every
|
|
387
|
+
// iteration regardless of success/failure. Skip on the last
|
|
388
|
+
// iteration because there is nothing left to fetch.
|
|
389
|
+
if (delaySeconds > 0 && idx < data.items.length - 1) {
|
|
390
|
+
await new Promise((r) => setTimeout(r, delaySeconds * 1000));
|
|
391
|
+
}
|
|
392
|
+
}
|
|
393
|
+
// Two-pass selection: sort by score desc, then (1) take the
|
|
394
|
+
// highest-quality result per unique host, (2) fill remaining
|
|
395
|
+
// slots from the leftovers. Mirrors Python skill.py:~495-540.
|
|
396
|
+
allCandidates.sort((a, b) => b.score - a.score);
|
|
397
|
+
const chosen = [];
|
|
398
|
+
const chosenHosts = new Set();
|
|
399
|
+
for (const cand of allCandidates) {
|
|
400
|
+
if (chosen.length >= count)
|
|
401
|
+
break;
|
|
402
|
+
if (!chosenHosts.has(cand.host)) {
|
|
403
|
+
chosen.push(cand);
|
|
404
|
+
chosenHosts.add(cand.host);
|
|
405
|
+
}
|
|
406
|
+
}
|
|
407
|
+
if (chosen.length < count) {
|
|
408
|
+
for (const cand of allCandidates) {
|
|
409
|
+
if (chosen.length >= count)
|
|
410
|
+
break;
|
|
411
|
+
if (!chosen.includes(cand))
|
|
412
|
+
chosen.push(cand);
|
|
413
|
+
}
|
|
414
|
+
}
|
|
415
|
+
const scored = chosen;
|
|
416
|
+
if (allCandidates.length === 0 || scored.length === 0) {
|
|
417
|
+
// Python skill.py:465-466 / 488-489 return a plain "no quality
|
|
418
|
+
// results" string, which the outer handler (skill.py:640-642)
|
|
419
|
+
// detects and replaces with the configured `no_results_message`.
|
|
420
|
+
// Skip the middleman and return the configured message directly.
|
|
421
|
+
return new FunctionResult(WebSearchSkill._formatNoResultsMessage(noResultsMessage, query));
|
|
422
|
+
}
|
|
423
|
+
// Per-result content budget — Python skill.py:491-495 divides
|
|
424
|
+
// by `len(best_results)` (the chosen count), not `num_results`,
|
|
425
|
+
// so under-filled result sets get more room per source.
|
|
426
|
+
const overheadPerResult = 400;
|
|
427
|
+
const availableForContent = maxContentLength - scored.length * overheadPerResult;
|
|
428
|
+
const perResultBudget = Math.max(2000, Math.floor(availableForContent / scored.length));
|
|
429
|
+
// Ranked-by-score output with full page content.
|
|
430
|
+
// Python skill.py:499-524 format — header lines + per-result
|
|
431
|
+
// block with Title / URL / Source / Snippet / Content Stats /
|
|
432
|
+
// Query Relevance / Content + 50-char separator.
|
|
433
|
+
const separator = '='.repeat(50);
|
|
434
|
+
const innerLines = [
|
|
435
|
+
`Found ${allCandidates.length} results meeting quality threshold from ${data.items.length} searched.`,
|
|
436
|
+
`Showing top ${scored.length} from diverse sources:\n`,
|
|
437
|
+
];
|
|
438
|
+
for (let i = 0; i < scored.length; i++) {
|
|
439
|
+
const cand = scored[i];
|
|
440
|
+
let block = `=== RESULT ${i + 1} (Quality: ${cand.score.toFixed(2)}) ===\n`;
|
|
441
|
+
block += `Title: ${cand.item.title}\n`;
|
|
442
|
+
block += `URL: ${cand.item.link}\n`;
|
|
443
|
+
block += `Source: ${cand.domain}\n`;
|
|
444
|
+
// Python skill.py:507 always prints `Snippet:` (empty when the
|
|
445
|
+
// Google result has no snippet). Mirror that for a stable layout.
|
|
446
|
+
const rawSnippet = cand.item.snippet ?? '';
|
|
447
|
+
block += `Snippet: ${rawSnippet.replace(/\n/g, ' ').trim()}\n`;
|
|
448
|
+
block += `Content Stats: ${cand.text_length} chars, ${cand.sentence_count} sentences\n`;
|
|
449
|
+
block += `Query Relevance: ${cand.query_relevance.toFixed(2)} (keywords: ${cand.query_words_found})\n`;
|
|
450
|
+
block += `Content:\n`;
|
|
451
|
+
let content = cand.text;
|
|
452
|
+
if (content.length > perResultBudget) {
|
|
453
|
+
content = content.slice(0, perResultBudget) + '...';
|
|
454
|
+
}
|
|
455
|
+
block += content;
|
|
456
|
+
// Python skill.py:523 — `f"\n{'='*50}\n\n"` (two trailing newlines).
|
|
457
|
+
block += `\n${separator}\n\n`;
|
|
458
|
+
innerLines.push(block);
|
|
459
|
+
}
|
|
460
|
+
const innerOutput = innerLines.join('\n');
|
|
461
|
+
// Python's outer `_web_search_handler` (skill.py:644) wraps the
|
|
462
|
+
// inner formatter output with a `"Quality web search results for
|
|
463
|
+
// '<query>':\n\n"` preamble.
|
|
464
|
+
return new FunctionResult(`Quality web search results for '${query}':\n\n${innerOutput}`);
|
|
465
|
+
}
|
|
466
|
+
catch (err) {
|
|
467
|
+
log.error('web_search_failed', {
|
|
468
|
+
error: err instanceof Error ? err.message : String(err),
|
|
469
|
+
});
|
|
470
|
+
return new FunctionResult('Sorry, I encountered an error while searching. Please try again later.');
|
|
471
|
+
}
|
|
472
|
+
},
|
|
473
|
+
},
|
|
474
|
+
];
|
|
475
|
+
}
|
|
476
|
+
/** Apply the `{query}` template to the no-results message. */
|
|
477
|
+
static _formatNoResultsMessage(template, query) {
|
|
478
|
+
return template.includes('{query}')
|
|
479
|
+
? template.replace(/\{query\}/g, query)
|
|
480
|
+
: template;
|
|
481
|
+
}
|
|
482
|
+
/**
|
|
483
|
+
* Check whether the URL points at Reddit. Python parity: `is_reddit_url`
|
|
484
|
+
* (skill.py:66).
|
|
485
|
+
*/
|
|
486
|
+
static _isRedditUrl(url) {
|
|
487
|
+
try {
|
|
488
|
+
const host = new URL(url).hostname.toLowerCase();
|
|
489
|
+
return host.includes('reddit.com') || host.includes('redd.it');
|
|
490
|
+
}
|
|
491
|
+
catch {
|
|
492
|
+
return false;
|
|
493
|
+
}
|
|
494
|
+
}
|
|
495
|
+
/**
|
|
496
|
+
* Fetch a Reddit URL via the `.json` endpoint and build a structured summary
|
|
497
|
+
* of the post + top comments.
|
|
498
|
+
*
|
|
499
|
+
* Python parity: `extract_reddit_content` (skill.py:71-190). Matches the
|
|
500
|
+
* post-title/author/score/comments assembly and the top-20 → valid → top-5
|
|
501
|
+
* comment pipeline. Returns just the compiled text — Python's
|
|
502
|
+
* `search_and_scrape_best` unconditionally overwrites Reddit's
|
|
503
|
+
* engagement-score metrics with the 6-factor `_calculate_content_quality`
|
|
504
|
+
* (skill.py:447-448), so we skip computing the dead engagement score here
|
|
505
|
+
* and let the handler score the text via `_qualityMetrics`.
|
|
506
|
+
*
|
|
507
|
+
* Falls through to HTML extraction on JSON fetch failure or malformed
|
|
508
|
+
* payload, matching Python's `except Exception: fall back` behavior.
|
|
509
|
+
*/
|
|
510
|
+
async _extractRedditContent(url, contentLimit, timeoutMs) {
|
|
511
|
+
try {
|
|
512
|
+
if (!(await validateUrl(url))) {
|
|
513
|
+
log.debug('web_search: reddit URL rejected by SSRF guard', { url });
|
|
514
|
+
return null;
|
|
515
|
+
}
|
|
516
|
+
const jsonUrl = url.endsWith('.json')
|
|
517
|
+
? url
|
|
518
|
+
: `${url.replace(/\/+$/, '')}.json`;
|
|
519
|
+
const controller = new AbortController();
|
|
520
|
+
const timer = setTimeout(() => controller.abort(), timeoutMs);
|
|
521
|
+
let response;
|
|
522
|
+
try {
|
|
523
|
+
response = await fetch(jsonUrl, {
|
|
524
|
+
signal: controller.signal,
|
|
525
|
+
headers: { 'User-Agent': 'SignalWire-WebSearch/2.0' },
|
|
526
|
+
});
|
|
527
|
+
}
|
|
528
|
+
finally {
|
|
529
|
+
clearTimeout(timer);
|
|
530
|
+
}
|
|
531
|
+
if (!response.ok) {
|
|
532
|
+
log.debug('web_search: reddit JSON non-200', {
|
|
533
|
+
url: jsonUrl,
|
|
534
|
+
status: response.status,
|
|
535
|
+
});
|
|
536
|
+
return null;
|
|
537
|
+
}
|
|
538
|
+
const data = (await response.json());
|
|
539
|
+
if (!Array.isArray(data) || data.length < 1) {
|
|
540
|
+
log.debug('web_search: reddit JSON structure invalid', { url });
|
|
541
|
+
return null;
|
|
542
|
+
}
|
|
543
|
+
const listing0 = data[0];
|
|
544
|
+
const postEntry = listing0?.data?.children?.[0]?.data;
|
|
545
|
+
if (!postEntry) {
|
|
546
|
+
log.debug('web_search: reddit post missing', { url });
|
|
547
|
+
return null;
|
|
548
|
+
}
|
|
549
|
+
const title = postEntry['title'] ?? 'No title';
|
|
550
|
+
const author = postEntry['author'] ?? 'unknown';
|
|
551
|
+
const postScore = postEntry['score'] ?? 0;
|
|
552
|
+
const numComments = postEntry['num_comments'] ?? 0;
|
|
553
|
+
const subreddit = postEntry['subreddit'] ?? '';
|
|
554
|
+
const selftext = (postEntry['selftext'] ?? '').trim();
|
|
555
|
+
const parts = [];
|
|
556
|
+
parts.push(`Reddit r/${subreddit} Discussion`);
|
|
557
|
+
parts.push(`\nPost: ${title}`);
|
|
558
|
+
parts.push(`Author: ${author} | Score: ${postScore} | Comments: ${numComments}`);
|
|
559
|
+
if (selftext && selftext !== '[removed]' && selftext !== '[deleted]') {
|
|
560
|
+
parts.push(`\nOriginal Post:\n${selftext.slice(0, 1000)}`);
|
|
561
|
+
}
|
|
562
|
+
const validComments = [];
|
|
563
|
+
if (data.length > 1) {
|
|
564
|
+
const listing1 = data[1];
|
|
565
|
+
const comments = listing1?.data?.children ?? [];
|
|
566
|
+
for (const c of comments.slice(0, 20)) {
|
|
567
|
+
if (c.kind !== 't1' || !c.data)
|
|
568
|
+
continue;
|
|
569
|
+
const body = (c.data['body'] ?? '').trim();
|
|
570
|
+
if (!body ||
|
|
571
|
+
body === '[removed]' ||
|
|
572
|
+
body === '[deleted]' ||
|
|
573
|
+
body.length <= 50) {
|
|
574
|
+
continue;
|
|
575
|
+
}
|
|
576
|
+
validComments.push({
|
|
577
|
+
body,
|
|
578
|
+
author: c.data['author'] ?? 'unknown',
|
|
579
|
+
score: c.data['score'] ?? 0,
|
|
580
|
+
});
|
|
581
|
+
}
|
|
582
|
+
validComments.sort((a, b) => b.score - a.score);
|
|
583
|
+
if (validComments.length > 0) {
|
|
584
|
+
parts.push('\n--- Top Discussion ---');
|
|
585
|
+
validComments.slice(0, 5).forEach((c, i) => {
|
|
586
|
+
let commentText = c.body.slice(0, 500);
|
|
587
|
+
if (c.body.length > 500)
|
|
588
|
+
commentText += '...';
|
|
589
|
+
parts.push(`\nComment ${i + 1} (Score: ${c.score}, Author: ${c.author}):`);
|
|
590
|
+
parts.push(commentText);
|
|
591
|
+
});
|
|
592
|
+
}
|
|
593
|
+
}
|
|
594
|
+
let text = parts.join('\n');
|
|
595
|
+
if (text.length > contentLimit) {
|
|
596
|
+
text = text.slice(0, contentLimit);
|
|
597
|
+
}
|
|
598
|
+
return { text };
|
|
599
|
+
}
|
|
600
|
+
catch (err) {
|
|
601
|
+
log.debug('web_search: reddit extraction failed', {
|
|
602
|
+
url,
|
|
603
|
+
error: err instanceof Error ? err.message : String(err),
|
|
604
|
+
});
|
|
605
|
+
return null;
|
|
606
|
+
}
|
|
607
|
+
}
|
|
608
|
+
/**
|
|
609
|
+
* Fetch a URL and extract clean text content, then score it with the
|
|
610
|
+
* 6-factor `_qualityMetrics`. Reddit URLs are routed to the JSON extractor
|
|
611
|
+
* first; the compiled Reddit text is scored with the same 6-factor formula
|
|
612
|
+
* to match Python's `search_and_scrape_best` overwrite behavior
|
|
613
|
+
* (skill.py:447-448).
|
|
614
|
+
*
|
|
615
|
+
* Python parity: `extract_text_from_url` (skill.py:192-202). Returns `null`
|
|
616
|
+
* on any failure (network, non-200, parse error, or SSRF rejection).
|
|
617
|
+
*/
|
|
618
|
+
async _scrapeUrl(url, contentLimit, timeoutMs, query) {
|
|
619
|
+
if (WebSearchSkill._isRedditUrl(url)) {
|
|
620
|
+
const reddit = await this._extractRedditContent(url, contentLimit, timeoutMs);
|
|
621
|
+
if (reddit) {
|
|
622
|
+
const metrics = WebSearchSkill._qualityMetrics(reddit.text, url, query);
|
|
623
|
+
return { text: reddit.text, ...metrics };
|
|
624
|
+
}
|
|
625
|
+
// Python skill.py:189-190 falls through to HTML extraction if the
|
|
626
|
+
// Reddit JSON path fails. Mirror that.
|
|
627
|
+
}
|
|
628
|
+
// SSRF guard — Python's scraper calls validate_url() before every
|
|
629
|
+
// requests.get() (skill.py:79-80, 209-210).
|
|
630
|
+
if (!(await validateUrl(url))) {
|
|
631
|
+
log.debug('web_search: scrape URL rejected by SSRF guard', { url });
|
|
632
|
+
return null;
|
|
633
|
+
}
|
|
634
|
+
const controller = new AbortController();
|
|
635
|
+
const timer = setTimeout(() => controller.abort(), timeoutMs);
|
|
636
|
+
try {
|
|
637
|
+
const response = await fetch(url, {
|
|
638
|
+
signal: controller.signal,
|
|
639
|
+
headers: {
|
|
640
|
+
'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
|
|
641
|
+
},
|
|
642
|
+
});
|
|
643
|
+
if (!response.ok) {
|
|
644
|
+
log.debug('web_search: scrape non-200', { url, status: response.status });
|
|
645
|
+
return null;
|
|
646
|
+
}
|
|
647
|
+
const body = await response.text();
|
|
648
|
+
let text = extractTextFromHtml(body);
|
|
649
|
+
if (text.length > contentLimit) {
|
|
650
|
+
text = text.slice(0, contentLimit);
|
|
651
|
+
}
|
|
652
|
+
if (!text)
|
|
653
|
+
return null;
|
|
654
|
+
const metrics = WebSearchSkill._qualityMetrics(text, url, query);
|
|
655
|
+
return { text, ...metrics };
|
|
656
|
+
}
|
|
657
|
+
catch (err) {
|
|
658
|
+
log.debug('web_search: scrape failed', {
|
|
659
|
+
url,
|
|
660
|
+
error: err instanceof Error ? err.message : String(err),
|
|
661
|
+
});
|
|
662
|
+
return null;
|
|
663
|
+
}
|
|
664
|
+
finally {
|
|
665
|
+
clearTimeout(timer);
|
|
666
|
+
}
|
|
667
|
+
}
|
|
668
|
+
/**
|
|
669
|
+
* Six-factor content quality metrics (score + sub-metrics used in the
|
|
670
|
+
* per-result output). Combines content length, word diversity,
|
|
671
|
+
* boilerplate penalty, sentence structure, domain reputation, and query
|
|
672
|
+
* relevance.
|
|
673
|
+
*
|
|
674
|
+
* Python parity: `_calculate_content_quality` (skill.py:284-414). Preserves
|
|
675
|
+
* the weights (0.25/0.10/0.10/0.15/0.15/0.25), the 26-phrase boilerplate
|
|
676
|
+
* list, the quality/low-quality domain lists, and the phrase-match bonus
|
|
677
|
+
* on relevance. Also returns the same metric fields Python exposes
|
|
678
|
+
* (`text_length`, `sentence_count`, `query_relevance`, `query_words_found`,
|
|
679
|
+
* `domain`) so the handler can render the full Python output format.
|
|
680
|
+
*/
|
|
681
|
+
static _qualityMetrics(text, url, query) {
|
|
682
|
+
if (!text) {
|
|
683
|
+
return {
|
|
684
|
+
score: 0,
|
|
685
|
+
text_length: 0,
|
|
686
|
+
sentence_count: 0,
|
|
687
|
+
query_relevance: 0,
|
|
688
|
+
query_words_found: 'N/A',
|
|
689
|
+
domain: '',
|
|
690
|
+
};
|
|
691
|
+
}
|
|
692
|
+
// 1. Length score — tiered bands (Python skill.py:300-310).
|
|
693
|
+
//
|
|
694
|
+
// Python's `len(text)` counts codepoints; JS's `text.length` counts
|
|
695
|
+
// UTF-16 code units, so any character outside the BMP (emoji, astral
|
|
696
|
+
// plane letters) counts as 2 in JS and 1 in Python. For emoji-heavy
|
|
697
|
+
// content that would inflate the TS length score relative to Python.
|
|
698
|
+
// Count codepoints explicitly to match Python.
|
|
699
|
+
const textLength = [...text].length;
|
|
700
|
+
let lengthScore;
|
|
701
|
+
if (textLength < 500) {
|
|
702
|
+
lengthScore = 0;
|
|
703
|
+
}
|
|
704
|
+
else if (textLength < 2000) {
|
|
705
|
+
lengthScore = ((textLength - 500) / 1500) * 0.5;
|
|
706
|
+
}
|
|
707
|
+
else if (textLength <= 10000) {
|
|
708
|
+
lengthScore = 1.0;
|
|
709
|
+
}
|
|
710
|
+
else {
|
|
711
|
+
lengthScore = Math.max(0.8, 1.0 - (textLength - 10000) / 20000);
|
|
712
|
+
}
|
|
713
|
+
// 2. Word diversity — unique / (total * 0.3). Python skill.py:313-321.
|
|
714
|
+
const words = text.toLowerCase().split(/\s+/).filter(Boolean);
|
|
715
|
+
const diversityScore = words.length === 0
|
|
716
|
+
? 0
|
|
717
|
+
: Math.min(1, new Set(words).size / (words.length * 0.3));
|
|
718
|
+
// 3. Boilerplate penalty — 26 phrases, -15% per phrase.
|
|
719
|
+
// Python skill.py:324-335.
|
|
720
|
+
const boilerplatePhrases = [
|
|
721
|
+
'cookie',
|
|
722
|
+
'privacy policy',
|
|
723
|
+
'terms of service',
|
|
724
|
+
'subscribe',
|
|
725
|
+
'sign up',
|
|
726
|
+
'log in',
|
|
727
|
+
'advertisement',
|
|
728
|
+
'sponsored',
|
|
729
|
+
'copyright',
|
|
730
|
+
'all rights reserved',
|
|
731
|
+
'skip to',
|
|
732
|
+
'navigation',
|
|
733
|
+
'breadcrumb',
|
|
734
|
+
'reddit inc',
|
|
735
|
+
'google llc',
|
|
736
|
+
'expand navigation',
|
|
737
|
+
'members •',
|
|
738
|
+
'archived post',
|
|
739
|
+
'votes cannot be cast',
|
|
740
|
+
'r/',
|
|
741
|
+
'subreddit',
|
|
742
|
+
'youtube',
|
|
743
|
+
'facebook',
|
|
744
|
+
'twitter',
|
|
745
|
+
'instagram',
|
|
746
|
+
'pinterest',
|
|
747
|
+
];
|
|
748
|
+
const lowerText = text.toLowerCase();
|
|
749
|
+
const boilerplateCount = boilerplatePhrases.reduce((n, phrase) => (lowerText.includes(phrase) ? n + 1 : n), 0);
|
|
750
|
+
const boilerplatePenalty = Math.max(0, 1 - boilerplateCount * 0.15);
|
|
751
|
+
// 4. Sentence score — count sentences with >30 chars; target 10.
|
|
752
|
+
// Python skill.py:339-342.
|
|
753
|
+
const sentences = text
|
|
754
|
+
.split(/[.!?]+/)
|
|
755
|
+
.filter((s) => s.trim().length > 30);
|
|
756
|
+
const sentenceScore = Math.min(1, sentences.length / 10);
|
|
757
|
+
// 5. Domain score — quality domains +1.5×, low-quality 0.1×, else 1.0.
|
|
758
|
+
// Python skill.py:344-365.
|
|
759
|
+
let domain = '';
|
|
760
|
+
try {
|
|
761
|
+
domain = new URL(url).hostname.toLowerCase();
|
|
762
|
+
}
|
|
763
|
+
catch {
|
|
764
|
+
domain = '';
|
|
765
|
+
}
|
|
766
|
+
const qualityDomains = [
|
|
767
|
+
'wikipedia.org',
|
|
768
|
+
'starwars.fandom.com',
|
|
769
|
+
'imdb.com',
|
|
770
|
+
'screenrant.com',
|
|
771
|
+
'denofgeek.com',
|
|
772
|
+
'ign.com',
|
|
773
|
+
'hollywoodreporter.com',
|
|
774
|
+
'variety.com',
|
|
775
|
+
'ew.com',
|
|
776
|
+
'stackexchange.com',
|
|
777
|
+
'stackoverflow.com',
|
|
778
|
+
'github.com',
|
|
779
|
+
'medium.com',
|
|
780
|
+
'dev.to',
|
|
781
|
+
'arxiv.org',
|
|
782
|
+
'nature.com',
|
|
783
|
+
'sciencedirect.com',
|
|
784
|
+
'ieee.org',
|
|
785
|
+
];
|
|
786
|
+
const lowQualityDomains = [
|
|
787
|
+
'reddit.com',
|
|
788
|
+
'youtube.com',
|
|
789
|
+
'facebook.com',
|
|
790
|
+
'twitter.com',
|
|
791
|
+
'instagram.com',
|
|
792
|
+
'pinterest.com',
|
|
793
|
+
'tiktok.com',
|
|
794
|
+
'x.com',
|
|
795
|
+
];
|
|
796
|
+
let domainScore = 1.0;
|
|
797
|
+
if (qualityDomains.some((d) => domain.includes(d))) {
|
|
798
|
+
domainScore = 1.5;
|
|
799
|
+
}
|
|
800
|
+
else if (lowQualityDomains.some((d) => domain.includes(d))) {
|
|
801
|
+
domainScore = 0.1;
|
|
802
|
+
}
|
|
803
|
+
// 6. Query relevance — word overlap + phrase bonus.
|
|
804
|
+
// Python skill.py:370-395.
|
|
805
|
+
const stopWords = new Set([
|
|
806
|
+
'the',
|
|
807
|
+
'a',
|
|
808
|
+
'an',
|
|
809
|
+
'and',
|
|
810
|
+
'or',
|
|
811
|
+
'but',
|
|
812
|
+
'in',
|
|
813
|
+
'on',
|
|
814
|
+
'at',
|
|
815
|
+
'to',
|
|
816
|
+
'for',
|
|
817
|
+
'of',
|
|
818
|
+
'with',
|
|
819
|
+
'by',
|
|
820
|
+
'from',
|
|
821
|
+
'as',
|
|
822
|
+
'is',
|
|
823
|
+
'was',
|
|
824
|
+
'are',
|
|
825
|
+
'were',
|
|
826
|
+
]);
|
|
827
|
+
const queryWords = query
|
|
828
|
+
.toLowerCase()
|
|
829
|
+
.split(/\s+/)
|
|
830
|
+
.filter((w) => w.length > 2 && !stopWords.has(w));
|
|
831
|
+
let relevanceScore;
|
|
832
|
+
let wordsFound = 'N/A';
|
|
833
|
+
if (queryWords.length === 0) {
|
|
834
|
+
relevanceScore = 0.5;
|
|
835
|
+
}
|
|
836
|
+
else {
|
|
837
|
+
const lowerContent = text.toLowerCase();
|
|
838
|
+
let hits = 0;
|
|
839
|
+
for (const w of queryWords) {
|
|
840
|
+
if (lowerContent.includes(w))
|
|
841
|
+
hits++;
|
|
842
|
+
}
|
|
843
|
+
let phraseBonus = 0;
|
|
844
|
+
for (let i = 0; i < queryWords.length - 1; i++) {
|
|
845
|
+
const phrase = `${queryWords[i]} ${queryWords[i + 1]}`;
|
|
846
|
+
if (lowerContent.includes(phrase))
|
|
847
|
+
phraseBonus += 0.2;
|
|
848
|
+
}
|
|
849
|
+
relevanceScore = Math.min(1, hits / queryWords.length + phraseBonus);
|
|
850
|
+
// Python skill.py:392 — `"{words_found}/{len(query_words)}"` string.
|
|
851
|
+
wordsFound = `${hits}/${queryWords.length}`;
|
|
852
|
+
}
|
|
853
|
+
// Weighted combination (Python skill.py:397-405).
|
|
854
|
+
const score = lengthScore * 0.25 +
|
|
855
|
+
diversityScore * 0.1 +
|
|
856
|
+
boilerplatePenalty * 0.1 +
|
|
857
|
+
sentenceScore * 0.15 +
|
|
858
|
+
domainScore * 0.15 +
|
|
859
|
+
relevanceScore * 0.25;
|
|
860
|
+
return {
|
|
861
|
+
score,
|
|
862
|
+
text_length: textLength,
|
|
863
|
+
sentence_count: sentences.length,
|
|
864
|
+
query_relevance: relevanceScore,
|
|
865
|
+
query_words_found: wordsFound,
|
|
866
|
+
domain,
|
|
867
|
+
};
|
|
868
|
+
}
|
|
869
|
+
/** @returns Prompt section describing web search capabilities and usage guidance. */
|
|
870
|
+
_getPromptSections() {
|
|
871
|
+
const toolName = this.getToolName();
|
|
872
|
+
return [
|
|
873
|
+
{
|
|
874
|
+
title: 'Web Search Capability (Quality Enhanced)',
|
|
875
|
+
body: `You can search the internet for high-quality information using the ${toolName} tool.`,
|
|
876
|
+
bullets: [
|
|
877
|
+
`Use the ${toolName} tool when users ask for information you need to look up`,
|
|
878
|
+
'The search automatically filters out low-quality results like empty pages',
|
|
879
|
+
'Results are ranked by content quality, relevance, and domain reputation',
|
|
880
|
+
'Summarize the high-quality results in a clear, helpful way',
|
|
881
|
+
],
|
|
882
|
+
},
|
|
883
|
+
];
|
|
884
|
+
}
|
|
885
|
+
}
|
|
886
|
+
/**
|
|
887
|
+
* Factory function for creating WebSearchSkill instances.
|
|
888
|
+
* @param config - Optional skill configuration.
|
|
889
|
+
* @returns A new WebSearchSkill instance.
|
|
890
|
+
*/
|
|
891
|
+
export function createSkill(config) {
|
|
892
|
+
return new WebSearchSkill(config);
|
|
893
|
+
}
|
|
894
|
+
//# sourceMappingURL=web_search.js.map
|