@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,1115 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* ContextBuilder - Contexts and Steps workflow system.
|
|
3
|
+
*
|
|
4
|
+
* Contexts contain ordered Steps, each with prompt text/POM sections,
|
|
5
|
+
* completion criteria, function restrictions, and navigation rules.
|
|
6
|
+
*/
|
|
7
|
+
const MAX_CONTEXTS = 50;
|
|
8
|
+
const MAX_STEPS_PER_CONTEXT = 100;
|
|
9
|
+
/**
|
|
10
|
+
* Reserved tool names auto-injected by the runtime when contexts/steps are
|
|
11
|
+
* present. User-defined SWAIG tools must not collide with these names.
|
|
12
|
+
*
|
|
13
|
+
* - `next_step` / `change_context` are injected when valid_steps or
|
|
14
|
+
* valid_contexts is set so the model can navigate the flow.
|
|
15
|
+
* - `gather_submit` is injected while a step's gather_info is collecting
|
|
16
|
+
* answers.
|
|
17
|
+
*
|
|
18
|
+
* ContextBuilder.validate() rejects any agent that registers a user tool
|
|
19
|
+
* sharing one of these names — the runtime would never call the user tool
|
|
20
|
+
* because the native one wins.
|
|
21
|
+
*/
|
|
22
|
+
export const RESERVED_NATIVE_TOOL_NAMES = new Set([
|
|
23
|
+
'next_step',
|
|
24
|
+
'change_context',
|
|
25
|
+
'gather_submit',
|
|
26
|
+
]);
|
|
27
|
+
// ── GatherQuestion ──────────────────────────────────────────────────
|
|
28
|
+
/** Represents a single question within a gather operation. */
|
|
29
|
+
export class GatherQuestion {
|
|
30
|
+
/** Unique key used to store the answer. */
|
|
31
|
+
key;
|
|
32
|
+
/** The question text presented to the user. */
|
|
33
|
+
question;
|
|
34
|
+
/** Expected answer type (e.g., "string", "number"). */
|
|
35
|
+
type;
|
|
36
|
+
/** Whether the answer requires user confirmation. */
|
|
37
|
+
confirm;
|
|
38
|
+
/** Optional additional prompt context for this question. */
|
|
39
|
+
prompt;
|
|
40
|
+
/** Optional list of SWAIG function names available during this question. */
|
|
41
|
+
functions;
|
|
42
|
+
/**
|
|
43
|
+
* Creates a new GatherQuestion.
|
|
44
|
+
* @param opts - Question configuration including key, question text, and optional type/confirm/prompt/functions.
|
|
45
|
+
*/
|
|
46
|
+
constructor(opts) {
|
|
47
|
+
this.key = opts.key;
|
|
48
|
+
this.question = opts.question;
|
|
49
|
+
this.type = opts.type ?? 'string';
|
|
50
|
+
this.confirm = opts.confirm ?? false;
|
|
51
|
+
this.prompt = opts.prompt;
|
|
52
|
+
this.functions = opts.functions;
|
|
53
|
+
}
|
|
54
|
+
/**
|
|
55
|
+
* Serializes this question to a plain object for SWML output.
|
|
56
|
+
* @returns A dictionary representation of this question.
|
|
57
|
+
*/
|
|
58
|
+
toDict() {
|
|
59
|
+
const d = { key: this.key, question: this.question };
|
|
60
|
+
if (this.type !== 'string')
|
|
61
|
+
d['type'] = this.type;
|
|
62
|
+
if (this.confirm)
|
|
63
|
+
d['confirm'] = true;
|
|
64
|
+
if (this.prompt)
|
|
65
|
+
d['prompt'] = this.prompt;
|
|
66
|
+
if (this.functions)
|
|
67
|
+
d['functions'] = this.functions;
|
|
68
|
+
return d;
|
|
69
|
+
}
|
|
70
|
+
}
|
|
71
|
+
// ── GatherInfo ──────────────────────────────────────────────────────
|
|
72
|
+
/** Collects structured information from the user through a series of questions. */
|
|
73
|
+
export class GatherInfo {
|
|
74
|
+
questions = [];
|
|
75
|
+
outputKey;
|
|
76
|
+
completionAction;
|
|
77
|
+
prompt;
|
|
78
|
+
/**
|
|
79
|
+
* Creates a new GatherInfo.
|
|
80
|
+
* @param opts - Optional output key, completion action, and prompt configuration.
|
|
81
|
+
*/
|
|
82
|
+
constructor(opts) {
|
|
83
|
+
this.outputKey = opts?.outputKey;
|
|
84
|
+
this.completionAction = opts?.completionAction;
|
|
85
|
+
this.prompt = opts?.prompt;
|
|
86
|
+
}
|
|
87
|
+
/**
|
|
88
|
+
* Adds a question to this gather operation.
|
|
89
|
+
* @param opts - Question configuration including key, question text, and optional type/confirm/prompt/functions.
|
|
90
|
+
* @returns This GatherInfo for chaining.
|
|
91
|
+
*/
|
|
92
|
+
addQuestion(opts) {
|
|
93
|
+
this.questions.push(new GatherQuestion(opts));
|
|
94
|
+
return this;
|
|
95
|
+
}
|
|
96
|
+
/**
|
|
97
|
+
* Returns all questions in this gather operation.
|
|
98
|
+
* @returns The array of GatherQuestion instances.
|
|
99
|
+
*/
|
|
100
|
+
getQuestions() {
|
|
101
|
+
return this.questions;
|
|
102
|
+
}
|
|
103
|
+
/**
|
|
104
|
+
* Returns the completion action for this gather info.
|
|
105
|
+
* @internal
|
|
106
|
+
*/
|
|
107
|
+
getCompletionAction() {
|
|
108
|
+
return this.completionAction;
|
|
109
|
+
}
|
|
110
|
+
/**
|
|
111
|
+
* Serializes this gather operation to a plain object for SWML output.
|
|
112
|
+
* @returns A dictionary representation of the gather info and its questions.
|
|
113
|
+
*/
|
|
114
|
+
toDict() {
|
|
115
|
+
if (!this.questions.length)
|
|
116
|
+
throw new Error('gather_info must have at least one question');
|
|
117
|
+
const d = { questions: this.questions.map((q) => q.toDict()) };
|
|
118
|
+
if (this.prompt)
|
|
119
|
+
d['prompt'] = this.prompt;
|
|
120
|
+
if (this.outputKey)
|
|
121
|
+
d['output_key'] = this.outputKey;
|
|
122
|
+
if (this.completionAction)
|
|
123
|
+
d['completion_action'] = this.completionAction;
|
|
124
|
+
return d;
|
|
125
|
+
}
|
|
126
|
+
}
|
|
127
|
+
/** A single step within a context, with prompt content, criteria, function restrictions, and navigation rules. */
|
|
128
|
+
export class Step {
|
|
129
|
+
/** The unique name identifying this step within its context. */
|
|
130
|
+
name;
|
|
131
|
+
text = null;
|
|
132
|
+
stepCriteria = null;
|
|
133
|
+
functions = null;
|
|
134
|
+
validSteps = null;
|
|
135
|
+
validContexts = null;
|
|
136
|
+
sections = [];
|
|
137
|
+
gatherInfo = null;
|
|
138
|
+
_end = false;
|
|
139
|
+
skipUserTurn = false;
|
|
140
|
+
_skipToNextStep = false;
|
|
141
|
+
resetSystemPrompt = null;
|
|
142
|
+
resetUserPrompt = null;
|
|
143
|
+
resetConsolidate = false;
|
|
144
|
+
resetFullReset = false;
|
|
145
|
+
/**
|
|
146
|
+
* Creates a new Step.
|
|
147
|
+
* @param name - The unique step name.
|
|
148
|
+
*/
|
|
149
|
+
constructor(name) {
|
|
150
|
+
this.name = name;
|
|
151
|
+
}
|
|
152
|
+
/**
|
|
153
|
+
* Sets raw text content for this step, mutually exclusive with POM sections.
|
|
154
|
+
* @param text - The raw prompt text.
|
|
155
|
+
* @returns This step for chaining.
|
|
156
|
+
*/
|
|
157
|
+
setText(text) {
|
|
158
|
+
if (this.sections.length)
|
|
159
|
+
throw new Error('Cannot use setText() when POM sections have been added.');
|
|
160
|
+
this.text = text;
|
|
161
|
+
return this;
|
|
162
|
+
}
|
|
163
|
+
/**
|
|
164
|
+
* Adds a POM section with a body, mutually exclusive with raw text.
|
|
165
|
+
* @param title - The section heading.
|
|
166
|
+
* @param body - The section body text.
|
|
167
|
+
* @returns This step for chaining.
|
|
168
|
+
*/
|
|
169
|
+
addSection(title, body) {
|
|
170
|
+
if (this.text !== null)
|
|
171
|
+
throw new Error('Cannot add POM sections when setText() has been used.');
|
|
172
|
+
this.sections.push({ title, body });
|
|
173
|
+
return this;
|
|
174
|
+
}
|
|
175
|
+
/**
|
|
176
|
+
* Adds a POM section with bullet points, mutually exclusive with raw text.
|
|
177
|
+
* @param title - The section heading.
|
|
178
|
+
* @param bullets - The list of bullet point strings.
|
|
179
|
+
* @returns This step for chaining.
|
|
180
|
+
*/
|
|
181
|
+
addBullets(title, bullets) {
|
|
182
|
+
if (this.text !== null)
|
|
183
|
+
throw new Error('Cannot add POM sections when setText() has been used.');
|
|
184
|
+
this.sections.push({ title, bullets });
|
|
185
|
+
return this;
|
|
186
|
+
}
|
|
187
|
+
/**
|
|
188
|
+
* Sets the criteria that must be met before this step is considered complete.
|
|
189
|
+
* @param criteria - A description of the completion criteria.
|
|
190
|
+
* @returns This step for chaining.
|
|
191
|
+
*/
|
|
192
|
+
setStepCriteria(criteria) {
|
|
193
|
+
this.stepCriteria = criteria;
|
|
194
|
+
return this;
|
|
195
|
+
}
|
|
196
|
+
/**
|
|
197
|
+
* Set which non-internal functions are callable while this step is active.
|
|
198
|
+
*
|
|
199
|
+
* IMPORTANT — inheritance behavior:
|
|
200
|
+
* If you do NOT call this method, the step inherits whichever function
|
|
201
|
+
* set was active on the previous step (or the previous context's last
|
|
202
|
+
* step). The server-side runtime only resets the active set when a
|
|
203
|
+
* step explicitly declares its `functions` field. This is by design,
|
|
204
|
+
* but it is the most common source of bugs in multi-step agents:
|
|
205
|
+
* forgetting setFunctions() on a later step lets the previous step's
|
|
206
|
+
* tools leak through.
|
|
207
|
+
*
|
|
208
|
+
* Best practice: call setFunctions() explicitly on every step that
|
|
209
|
+
* should have a different toolset than the previous one.
|
|
210
|
+
*
|
|
211
|
+
* Keep the per-step active set small: LLM tool selection accuracy
|
|
212
|
+
* degrades noticeably past ~7-8 simultaneously-active tools per call.
|
|
213
|
+
* Use per-step whitelisting to partition large tool collections.
|
|
214
|
+
*
|
|
215
|
+
* Internal functions (e.g. `startup_hook`, `hangup_hook`, `gather_submit`)
|
|
216
|
+
* are ALWAYS protected and cannot be deactivated by this whitelist. The
|
|
217
|
+
* native navigation tools `next_step` and `change_context` are injected
|
|
218
|
+
* automatically when validSteps/validContexts is set; they are not
|
|
219
|
+
* affected by this list and do not need to appear in it.
|
|
220
|
+
*
|
|
221
|
+
* @param functions - One of:
|
|
222
|
+
* - `string[]` — whitelist of function names allowed in this step.
|
|
223
|
+
* Functions not in the list become inactive.
|
|
224
|
+
* - `[]` — explicit disable-all (no user functions callable).
|
|
225
|
+
* - `"none"` — synonym for `[]`, same effect.
|
|
226
|
+
* @returns This step for chaining.
|
|
227
|
+
*
|
|
228
|
+
* @example
|
|
229
|
+
* step.setFunctions(['lookup_account', 'check_balance']); // whitelist
|
|
230
|
+
* step.setFunctions([]); // disable all
|
|
231
|
+
* step.setFunctions('none'); // disable all (alt)
|
|
232
|
+
*/
|
|
233
|
+
setFunctions(functions) {
|
|
234
|
+
this.functions = functions;
|
|
235
|
+
return this;
|
|
236
|
+
}
|
|
237
|
+
/**
|
|
238
|
+
* Sets which steps the AI may navigate to from this step.
|
|
239
|
+
* @param steps - List of allowed step names.
|
|
240
|
+
* @returns This step for chaining.
|
|
241
|
+
*/
|
|
242
|
+
setValidSteps(steps) {
|
|
243
|
+
this.validSteps = steps;
|
|
244
|
+
return this;
|
|
245
|
+
}
|
|
246
|
+
/**
|
|
247
|
+
* Sets which contexts the AI may navigate to from this step.
|
|
248
|
+
* @param contexts - List of allowed context names.
|
|
249
|
+
* @returns This step for chaining.
|
|
250
|
+
*/
|
|
251
|
+
setValidContexts(contexts) {
|
|
252
|
+
this.validContexts = contexts;
|
|
253
|
+
return this;
|
|
254
|
+
}
|
|
255
|
+
/**
|
|
256
|
+
* Mark this step as terminal for the step flow.
|
|
257
|
+
*
|
|
258
|
+
* IMPORTANT: `end=true` does NOT end the conversation or hang up the
|
|
259
|
+
* call. It exits step mode entirely after this step executes — clearing
|
|
260
|
+
* the steps list, current step index, validSteps, and validContexts.
|
|
261
|
+
* The agent keeps running, but operates only under the base system
|
|
262
|
+
* prompt and the context-level prompt; no more step instructions are
|
|
263
|
+
* injected and no more `next_step` tool is offered.
|
|
264
|
+
*
|
|
265
|
+
* To actually end the call, call a hangup tool or define a hangup hook.
|
|
266
|
+
*
|
|
267
|
+
* @param end - True to exit step mode after this step.
|
|
268
|
+
* @returns This step for chaining.
|
|
269
|
+
*/
|
|
270
|
+
setEnd(end) {
|
|
271
|
+
this._end = end;
|
|
272
|
+
return this;
|
|
273
|
+
}
|
|
274
|
+
/**
|
|
275
|
+
* Sets whether to skip waiting for user input when entering this step.
|
|
276
|
+
* @param skip - Whether to skip the user turn.
|
|
277
|
+
* @returns This step for chaining.
|
|
278
|
+
*/
|
|
279
|
+
setSkipUserTurn(skip) {
|
|
280
|
+
this.skipUserTurn = skip;
|
|
281
|
+
return this;
|
|
282
|
+
}
|
|
283
|
+
/**
|
|
284
|
+
* Sets whether to automatically advance to the next step after this one completes.
|
|
285
|
+
* @param skip - Whether to skip to the next step.
|
|
286
|
+
* @returns This step for chaining.
|
|
287
|
+
*/
|
|
288
|
+
setSkipToNextStep(skip) {
|
|
289
|
+
this._skipToNextStep = skip;
|
|
290
|
+
return this;
|
|
291
|
+
}
|
|
292
|
+
/**
|
|
293
|
+
* Initializes a gather info operation on this step for collecting structured data.
|
|
294
|
+
* @param opts - Optional output key, completion action, and prompt configuration.
|
|
295
|
+
* @returns This step for chaining.
|
|
296
|
+
*/
|
|
297
|
+
setGatherInfo(opts) {
|
|
298
|
+
this.gatherInfo = new GatherInfo(opts);
|
|
299
|
+
return this;
|
|
300
|
+
}
|
|
301
|
+
/**
|
|
302
|
+
* Add a question to this step's gather_info configuration.
|
|
303
|
+
* setGatherInfo() must be called before this method.
|
|
304
|
+
*
|
|
305
|
+
* IMPORTANT — gather mode locks function access:
|
|
306
|
+
* While the model is asking gather questions, the runtime forcibly
|
|
307
|
+
* deactivates ALL of the step's other functions. The only callable
|
|
308
|
+
* tools during a gather question are:
|
|
309
|
+
*
|
|
310
|
+
* - `gather_submit` (the native answer-submission tool)
|
|
311
|
+
* - Whatever names you list in this question's `functions` option
|
|
312
|
+
*
|
|
313
|
+
* `next_step` and `change_context` are also filtered out — the model
|
|
314
|
+
* cannot navigate away until the gather completes. This is by design:
|
|
315
|
+
* it forces a tight ask → submit → next-question loop.
|
|
316
|
+
*
|
|
317
|
+
* If a question needs to call out to a tool (e.g. validate an email,
|
|
318
|
+
* geocode a ZIP), list that tool name in this question's `functions`.
|
|
319
|
+
* Functions listed here are active ONLY for this question.
|
|
320
|
+
*
|
|
321
|
+
* @param opts - Question configuration including key, question text, and optional type/confirm/prompt/functions.
|
|
322
|
+
* @returns This step for chaining.
|
|
323
|
+
*/
|
|
324
|
+
addGatherQuestion(opts) {
|
|
325
|
+
if (!this.gatherInfo)
|
|
326
|
+
throw new Error('Must call setGatherInfo() before addGatherQuestion()');
|
|
327
|
+
this.gatherInfo.addQuestion(opts);
|
|
328
|
+
return this;
|
|
329
|
+
}
|
|
330
|
+
/**
|
|
331
|
+
* Returns the gather info for this step, if any.
|
|
332
|
+
* @internal
|
|
333
|
+
*/
|
|
334
|
+
getGatherInfo() {
|
|
335
|
+
return this.gatherInfo;
|
|
336
|
+
}
|
|
337
|
+
/**
|
|
338
|
+
* Returns the valid steps list for this step, if any.
|
|
339
|
+
* @internal
|
|
340
|
+
*/
|
|
341
|
+
getValidSteps() {
|
|
342
|
+
return this.validSteps;
|
|
343
|
+
}
|
|
344
|
+
/**
|
|
345
|
+
* Returns the valid contexts list for this step, if any.
|
|
346
|
+
* @internal
|
|
347
|
+
*/
|
|
348
|
+
getStepValidContexts() {
|
|
349
|
+
return this.validContexts;
|
|
350
|
+
}
|
|
351
|
+
/**
|
|
352
|
+
* Removes all POM sections and raw text from this step.
|
|
353
|
+
* @returns This step for chaining.
|
|
354
|
+
*/
|
|
355
|
+
clearSections() {
|
|
356
|
+
this.sections = [];
|
|
357
|
+
this.text = null;
|
|
358
|
+
return this;
|
|
359
|
+
}
|
|
360
|
+
/**
|
|
361
|
+
* Sets the system prompt to use when resetting context at this step.
|
|
362
|
+
* @param systemPrompt - The replacement system prompt text.
|
|
363
|
+
* @returns This step for chaining.
|
|
364
|
+
*/
|
|
365
|
+
setResetSystemPrompt(systemPrompt) {
|
|
366
|
+
this.resetSystemPrompt = systemPrompt;
|
|
367
|
+
return this;
|
|
368
|
+
}
|
|
369
|
+
/**
|
|
370
|
+
* Sets the user prompt to use when resetting context at this step.
|
|
371
|
+
* @param userPrompt - The replacement user prompt text.
|
|
372
|
+
* @returns This step for chaining.
|
|
373
|
+
*/
|
|
374
|
+
setResetUserPrompt(userPrompt) {
|
|
375
|
+
this.resetUserPrompt = userPrompt;
|
|
376
|
+
return this;
|
|
377
|
+
}
|
|
378
|
+
/**
|
|
379
|
+
* Sets whether to consolidate conversation history when resetting at this step.
|
|
380
|
+
* @param consolidate - Whether to consolidate.
|
|
381
|
+
* @returns This step for chaining.
|
|
382
|
+
*/
|
|
383
|
+
setResetConsolidate(consolidate) {
|
|
384
|
+
this.resetConsolidate = consolidate;
|
|
385
|
+
return this;
|
|
386
|
+
}
|
|
387
|
+
/**
|
|
388
|
+
* Sets whether to perform a full conversation reset at this step.
|
|
389
|
+
* @param fullReset - Whether to fully reset.
|
|
390
|
+
* @returns This step for chaining.
|
|
391
|
+
*/
|
|
392
|
+
setResetFullReset(fullReset) {
|
|
393
|
+
this.resetFullReset = fullReset;
|
|
394
|
+
return this;
|
|
395
|
+
}
|
|
396
|
+
renderText() {
|
|
397
|
+
if (this.text !== null)
|
|
398
|
+
return this.text;
|
|
399
|
+
if (!this.sections.length)
|
|
400
|
+
throw new Error(`Step '${this.name}' has no text or POM sections defined`);
|
|
401
|
+
const parts = [];
|
|
402
|
+
for (const section of this.sections) {
|
|
403
|
+
parts.push(`## ${section.title}`);
|
|
404
|
+
if (section.bullets) {
|
|
405
|
+
for (const b of section.bullets)
|
|
406
|
+
parts.push(`- ${b}`);
|
|
407
|
+
}
|
|
408
|
+
else if (section.body) {
|
|
409
|
+
parts.push(section.body);
|
|
410
|
+
}
|
|
411
|
+
parts.push('');
|
|
412
|
+
}
|
|
413
|
+
return parts.join('\n').trim();
|
|
414
|
+
}
|
|
415
|
+
/**
|
|
416
|
+
* Serializes this step to a plain object for SWML output.
|
|
417
|
+
* @returns A dictionary representation of this step.
|
|
418
|
+
*/
|
|
419
|
+
toDict() {
|
|
420
|
+
const d = { name: this.name, text: this.renderText() };
|
|
421
|
+
if (this.stepCriteria)
|
|
422
|
+
d['step_criteria'] = this.stepCriteria;
|
|
423
|
+
if (this.functions !== null)
|
|
424
|
+
d['functions'] = this.functions;
|
|
425
|
+
if (this.validSteps !== null)
|
|
426
|
+
d['valid_steps'] = this.validSteps;
|
|
427
|
+
if (this.validContexts !== null)
|
|
428
|
+
d['valid_contexts'] = this.validContexts;
|
|
429
|
+
if (this._end)
|
|
430
|
+
d['end'] = true;
|
|
431
|
+
if (this.skipUserTurn)
|
|
432
|
+
d['skip_user_turn'] = true;
|
|
433
|
+
if (this._skipToNextStep)
|
|
434
|
+
d['skip_to_next_step'] = true;
|
|
435
|
+
const reset = {};
|
|
436
|
+
if (this.resetSystemPrompt !== null)
|
|
437
|
+
reset['system_prompt'] = this.resetSystemPrompt;
|
|
438
|
+
if (this.resetUserPrompt !== null)
|
|
439
|
+
reset['user_prompt'] = this.resetUserPrompt;
|
|
440
|
+
if (this.resetConsolidate)
|
|
441
|
+
reset['consolidate'] = true;
|
|
442
|
+
if (this.resetFullReset)
|
|
443
|
+
reset['full_reset'] = true;
|
|
444
|
+
if (Object.keys(reset).length)
|
|
445
|
+
d['reset'] = reset;
|
|
446
|
+
if (this.gatherInfo)
|
|
447
|
+
d['gather_info'] = this.gatherInfo.toDict();
|
|
448
|
+
return d;
|
|
449
|
+
}
|
|
450
|
+
}
|
|
451
|
+
// ── Context ─────────────────────────────────────────────────────────
|
|
452
|
+
/** A named context containing ordered steps, prompt configuration, and navigation rules. */
|
|
453
|
+
export class Context {
|
|
454
|
+
/** The unique name identifying this context. */
|
|
455
|
+
name;
|
|
456
|
+
steps = new Map();
|
|
457
|
+
stepOrder = [];
|
|
458
|
+
_validContexts = null;
|
|
459
|
+
_validSteps = null;
|
|
460
|
+
_postPrompt = null;
|
|
461
|
+
_systemPrompt = null;
|
|
462
|
+
systemPromptSections = [];
|
|
463
|
+
_consolidate = false;
|
|
464
|
+
_fullReset = false;
|
|
465
|
+
_userPrompt = null;
|
|
466
|
+
_isolated = false;
|
|
467
|
+
promptText = null;
|
|
468
|
+
promptSections = [];
|
|
469
|
+
_initialStep = null;
|
|
470
|
+
_enterFillers = null;
|
|
471
|
+
_exitFillers = null;
|
|
472
|
+
/**
|
|
473
|
+
* Creates a new Context.
|
|
474
|
+
* @param name - The unique context name.
|
|
475
|
+
*/
|
|
476
|
+
constructor(name) {
|
|
477
|
+
this.name = name;
|
|
478
|
+
}
|
|
479
|
+
/**
|
|
480
|
+
* Adds a new step to this context.
|
|
481
|
+
* @param name - The unique step name within this context.
|
|
482
|
+
* @param opts - Optional shorthand for task text, bullets, criteria, functions, and valid steps.
|
|
483
|
+
* @returns The newly created Step for further configuration.
|
|
484
|
+
*/
|
|
485
|
+
addStep(name, opts) {
|
|
486
|
+
if (this.steps.size >= MAX_STEPS_PER_CONTEXT) {
|
|
487
|
+
throw new Error(`Maximum steps per context (${MAX_STEPS_PER_CONTEXT}) exceeded`);
|
|
488
|
+
}
|
|
489
|
+
if (this.steps.has(name))
|
|
490
|
+
throw new Error(`Step '${name}' already exists in context '${this.name}'`);
|
|
491
|
+
const step = new Step(name);
|
|
492
|
+
this.steps.set(name, step);
|
|
493
|
+
this.stepOrder.push(name);
|
|
494
|
+
if (opts?.task)
|
|
495
|
+
step.addSection('Task', opts.task);
|
|
496
|
+
if (opts?.bullets)
|
|
497
|
+
step.addBullets('Process', opts.bullets);
|
|
498
|
+
if (opts?.criteria)
|
|
499
|
+
step.setStepCriteria(opts.criteria);
|
|
500
|
+
if (opts?.functions)
|
|
501
|
+
step.setFunctions(opts.functions);
|
|
502
|
+
if (opts?.validSteps)
|
|
503
|
+
step.setValidSteps(opts.validSteps);
|
|
504
|
+
return step;
|
|
505
|
+
}
|
|
506
|
+
/**
|
|
507
|
+
* Returns a step by name.
|
|
508
|
+
* @param name - The step name to retrieve.
|
|
509
|
+
* @returns The matching Step, or undefined if not found.
|
|
510
|
+
*/
|
|
511
|
+
getStep(name) {
|
|
512
|
+
return this.steps.get(name);
|
|
513
|
+
}
|
|
514
|
+
/**
|
|
515
|
+
* Removes a step from this context by name.
|
|
516
|
+
* @param name - The step name to remove.
|
|
517
|
+
* @returns This context for chaining.
|
|
518
|
+
*/
|
|
519
|
+
removeStep(name) {
|
|
520
|
+
this.steps.delete(name);
|
|
521
|
+
this.stepOrder = this.stepOrder.filter((s) => s !== name);
|
|
522
|
+
return this;
|
|
523
|
+
}
|
|
524
|
+
/**
|
|
525
|
+
* Moves a step to a new position in the step order.
|
|
526
|
+
* @param name - The step name to move.
|
|
527
|
+
* @param position - The zero-based index to insert at.
|
|
528
|
+
* @returns This context for chaining.
|
|
529
|
+
*/
|
|
530
|
+
moveStep(name, position) {
|
|
531
|
+
if (!this.steps.has(name))
|
|
532
|
+
throw new Error(`Step '${name}' not found in context '${this.name}'`);
|
|
533
|
+
this.stepOrder = this.stepOrder.filter((s) => s !== name);
|
|
534
|
+
this.stepOrder.splice(position, 0, name);
|
|
535
|
+
return this;
|
|
536
|
+
}
|
|
537
|
+
/**
|
|
538
|
+
* Sets which contexts the AI may navigate to from this context.
|
|
539
|
+
* @param contexts - List of allowed context names.
|
|
540
|
+
* @returns This context for chaining.
|
|
541
|
+
*/
|
|
542
|
+
setValidContexts(contexts) {
|
|
543
|
+
this._validContexts = contexts;
|
|
544
|
+
return this;
|
|
545
|
+
}
|
|
546
|
+
/**
|
|
547
|
+
* Sets which steps the AI may navigate to from this context.
|
|
548
|
+
* @param steps - List of allowed step names.
|
|
549
|
+
* @returns This context for chaining.
|
|
550
|
+
*/
|
|
551
|
+
setValidSteps(steps) {
|
|
552
|
+
this._validSteps = steps;
|
|
553
|
+
return this;
|
|
554
|
+
}
|
|
555
|
+
/**
|
|
556
|
+
* Sets the post-prompt text for this context.
|
|
557
|
+
* @param postPrompt - The post-prompt string.
|
|
558
|
+
* @returns This context for chaining.
|
|
559
|
+
*/
|
|
560
|
+
setPostPrompt(postPrompt) {
|
|
561
|
+
this._postPrompt = postPrompt;
|
|
562
|
+
return this;
|
|
563
|
+
}
|
|
564
|
+
/**
|
|
565
|
+
* Sets raw system prompt text, mutually exclusive with system POM sections.
|
|
566
|
+
* @param systemPrompt - The system prompt string.
|
|
567
|
+
* @returns This context for chaining.
|
|
568
|
+
*/
|
|
569
|
+
setSystemPrompt(systemPrompt) {
|
|
570
|
+
if (this.systemPromptSections.length)
|
|
571
|
+
throw new Error('Cannot use setSystemPrompt() when POM sections have been added.');
|
|
572
|
+
this._systemPrompt = systemPrompt;
|
|
573
|
+
return this;
|
|
574
|
+
}
|
|
575
|
+
/**
|
|
576
|
+
* Sets whether to consolidate conversation history when entering this context.
|
|
577
|
+
* @param consolidate - Whether to consolidate.
|
|
578
|
+
* @returns This context for chaining.
|
|
579
|
+
*/
|
|
580
|
+
setConsolidate(consolidate) {
|
|
581
|
+
this._consolidate = consolidate;
|
|
582
|
+
return this;
|
|
583
|
+
}
|
|
584
|
+
/**
|
|
585
|
+
* Sets whether to fully reset conversation history when entering this context.
|
|
586
|
+
* @param fullReset - Whether to fully reset.
|
|
587
|
+
* @returns This context for chaining.
|
|
588
|
+
*/
|
|
589
|
+
setFullReset(fullReset) {
|
|
590
|
+
this._fullReset = fullReset;
|
|
591
|
+
return this;
|
|
592
|
+
}
|
|
593
|
+
/**
|
|
594
|
+
* Sets the user prompt text for this context.
|
|
595
|
+
* @param userPrompt - The user prompt string.
|
|
596
|
+
* @returns This context for chaining.
|
|
597
|
+
*/
|
|
598
|
+
setUserPrompt(userPrompt) {
|
|
599
|
+
this._userPrompt = userPrompt;
|
|
600
|
+
return this;
|
|
601
|
+
}
|
|
602
|
+
/**
|
|
603
|
+
* Set which step the context starts on when entered.
|
|
604
|
+
*
|
|
605
|
+
* By default, a context starts on its first step (index 0). Use this to
|
|
606
|
+
* skip a preamble step on re-entry via `change_context`.
|
|
607
|
+
*
|
|
608
|
+
* @param stepName - Name of the step to start on. Must exist in this context (validated by ContextBuilder.validate()).
|
|
609
|
+
* @returns This context for chaining.
|
|
610
|
+
*/
|
|
611
|
+
setInitialStep(stepName) {
|
|
612
|
+
this._initialStep = stepName;
|
|
613
|
+
return this;
|
|
614
|
+
}
|
|
615
|
+
/**
|
|
616
|
+
* Mark this context as isolated — entering it wipes conversation history.
|
|
617
|
+
*
|
|
618
|
+
* When `isolated=true` and the context is entered via change_context, the
|
|
619
|
+
* runtime wipes the conversation array. The model starts fresh with only
|
|
620
|
+
* the new context's systemPrompt + step instructions, with no memory of
|
|
621
|
+
* prior turns.
|
|
622
|
+
*
|
|
623
|
+
* EXCEPTION — `reset` overrides the wipe:
|
|
624
|
+
* If the context also has a `reset` configuration (via consolidate or
|
|
625
|
+
* full_reset), the wipe is skipped in favor of the reset behavior. Use
|
|
626
|
+
* reset with consolidate=true to summarize prior history into a single
|
|
627
|
+
* message instead of dropping it entirely.
|
|
628
|
+
*
|
|
629
|
+
* Use cases:
|
|
630
|
+
* - Switching to a sensitive billing flow that should not see prior
|
|
631
|
+
* small-talk
|
|
632
|
+
* - Handing off to a different agent persona
|
|
633
|
+
* - Resetting after a long off-topic detour
|
|
634
|
+
*
|
|
635
|
+
* @param isolated - True to wipe conversation history on context entry
|
|
636
|
+
* (subject to the reset exception above).
|
|
637
|
+
* @returns This context for chaining.
|
|
638
|
+
*/
|
|
639
|
+
setIsolated(isolated) {
|
|
640
|
+
this._isolated = isolated;
|
|
641
|
+
return this;
|
|
642
|
+
}
|
|
643
|
+
/**
|
|
644
|
+
* Adds a POM section to the system prompt, mutually exclusive with raw system prompt text.
|
|
645
|
+
* @param title - The section heading.
|
|
646
|
+
* @param body - The section body text.
|
|
647
|
+
* @returns This context for chaining.
|
|
648
|
+
*/
|
|
649
|
+
addSystemSection(title, body) {
|
|
650
|
+
if (this._systemPrompt !== null)
|
|
651
|
+
throw new Error('Cannot add POM sections when setSystemPrompt() has been used.');
|
|
652
|
+
this.systemPromptSections.push({ title, body });
|
|
653
|
+
return this;
|
|
654
|
+
}
|
|
655
|
+
/**
|
|
656
|
+
* Adds a POM section with bullets to the system prompt, mutually exclusive with raw system prompt text.
|
|
657
|
+
* @param title - The section heading.
|
|
658
|
+
* @param bullets - The list of bullet point strings.
|
|
659
|
+
* @returns This context for chaining.
|
|
660
|
+
*/
|
|
661
|
+
addSystemBullets(title, bullets) {
|
|
662
|
+
if (this._systemPrompt !== null)
|
|
663
|
+
throw new Error('Cannot add POM sections when setSystemPrompt() has been used.');
|
|
664
|
+
this.systemPromptSections.push({ title, bullets });
|
|
665
|
+
return this;
|
|
666
|
+
}
|
|
667
|
+
/**
|
|
668
|
+
* Sets raw prompt text for this context, mutually exclusive with POM prompt sections.
|
|
669
|
+
* @param prompt - The prompt string.
|
|
670
|
+
* @returns This context for chaining.
|
|
671
|
+
*/
|
|
672
|
+
setPrompt(prompt) {
|
|
673
|
+
if (this.promptSections.length)
|
|
674
|
+
throw new Error('Cannot use setPrompt() when POM sections have been added.');
|
|
675
|
+
this.promptText = prompt;
|
|
676
|
+
return this;
|
|
677
|
+
}
|
|
678
|
+
/**
|
|
679
|
+
* Adds a POM section with a body to the context prompt, mutually exclusive with raw prompt text.
|
|
680
|
+
* @param title - The section heading.
|
|
681
|
+
* @param body - The section body text.
|
|
682
|
+
* @returns This context for chaining.
|
|
683
|
+
*/
|
|
684
|
+
addSection(title, body) {
|
|
685
|
+
if (this.promptText !== null)
|
|
686
|
+
throw new Error('Cannot add POM sections when setPrompt() has been used.');
|
|
687
|
+
this.promptSections.push({ title, body });
|
|
688
|
+
return this;
|
|
689
|
+
}
|
|
690
|
+
/**
|
|
691
|
+
* Adds a POM section with bullets to the context prompt, mutually exclusive with raw prompt text.
|
|
692
|
+
* @param title - The section heading.
|
|
693
|
+
* @param bullets - The list of bullet point strings.
|
|
694
|
+
* @returns This context for chaining.
|
|
695
|
+
*/
|
|
696
|
+
addBullets(title, bullets) {
|
|
697
|
+
if (this.promptText !== null)
|
|
698
|
+
throw new Error('Cannot add POM sections when setPrompt() has been used.');
|
|
699
|
+
this.promptSections.push({ title, bullets });
|
|
700
|
+
return this;
|
|
701
|
+
}
|
|
702
|
+
/**
|
|
703
|
+
* Sets filler phrases spoken when entering this context, keyed by language code.
|
|
704
|
+
* @param fillers - Map of language codes to arrays of filler phrases.
|
|
705
|
+
* @returns This context for chaining.
|
|
706
|
+
*/
|
|
707
|
+
setEnterFillers(fillers) {
|
|
708
|
+
this._enterFillers = fillers;
|
|
709
|
+
return this;
|
|
710
|
+
}
|
|
711
|
+
/**
|
|
712
|
+
* Sets filler phrases spoken when exiting this context, keyed by language code.
|
|
713
|
+
* @param fillers - Map of language codes to arrays of filler phrases.
|
|
714
|
+
* @returns This context for chaining.
|
|
715
|
+
*/
|
|
716
|
+
setExitFillers(fillers) {
|
|
717
|
+
this._exitFillers = fillers;
|
|
718
|
+
return this;
|
|
719
|
+
}
|
|
720
|
+
/**
|
|
721
|
+
* Adds enter filler phrases for a specific language.
|
|
722
|
+
* @param languageCode - The language code (e.g., "en-US").
|
|
723
|
+
* @param fillers - Array of filler phrases.
|
|
724
|
+
* @returns This context for chaining.
|
|
725
|
+
*/
|
|
726
|
+
addEnterFiller(languageCode, fillers) {
|
|
727
|
+
if (!this._enterFillers)
|
|
728
|
+
this._enterFillers = {};
|
|
729
|
+
this._enterFillers[languageCode] = fillers;
|
|
730
|
+
return this;
|
|
731
|
+
}
|
|
732
|
+
/**
|
|
733
|
+
* Adds exit filler phrases for a specific language.
|
|
734
|
+
* @param languageCode - The language code (e.g., "en-US").
|
|
735
|
+
* @param fillers - Array of filler phrases.
|
|
736
|
+
* @returns This context for chaining.
|
|
737
|
+
*/
|
|
738
|
+
addExitFiller(languageCode, fillers) {
|
|
739
|
+
if (!this._exitFillers)
|
|
740
|
+
this._exitFillers = {};
|
|
741
|
+
this._exitFillers[languageCode] = fillers;
|
|
742
|
+
return this;
|
|
743
|
+
}
|
|
744
|
+
/** @internal */
|
|
745
|
+
getSteps() {
|
|
746
|
+
return this.steps;
|
|
747
|
+
}
|
|
748
|
+
/** @internal */
|
|
749
|
+
getStepOrder() {
|
|
750
|
+
return this.stepOrder;
|
|
751
|
+
}
|
|
752
|
+
/** @internal */
|
|
753
|
+
getInitialStep() {
|
|
754
|
+
return this._initialStep;
|
|
755
|
+
}
|
|
756
|
+
/** @internal */
|
|
757
|
+
getValidContexts() {
|
|
758
|
+
return this._validContexts;
|
|
759
|
+
}
|
|
760
|
+
renderPrompt() {
|
|
761
|
+
if (this.promptText !== null)
|
|
762
|
+
return this.promptText;
|
|
763
|
+
if (!this.promptSections.length)
|
|
764
|
+
return null;
|
|
765
|
+
return this.renderSections(this.promptSections);
|
|
766
|
+
}
|
|
767
|
+
renderSystemPrompt() {
|
|
768
|
+
if (this._systemPrompt !== null)
|
|
769
|
+
return this._systemPrompt;
|
|
770
|
+
if (!this.systemPromptSections.length)
|
|
771
|
+
return null;
|
|
772
|
+
return this.renderSections(this.systemPromptSections);
|
|
773
|
+
}
|
|
774
|
+
renderSections(sections) {
|
|
775
|
+
const parts = [];
|
|
776
|
+
for (const s of sections) {
|
|
777
|
+
parts.push(`## ${s.title}`);
|
|
778
|
+
if (s.bullets)
|
|
779
|
+
for (const b of s.bullets)
|
|
780
|
+
parts.push(`- ${b}`);
|
|
781
|
+
else if (s.body)
|
|
782
|
+
parts.push(s.body);
|
|
783
|
+
parts.push('');
|
|
784
|
+
}
|
|
785
|
+
return parts.join('\n').trim();
|
|
786
|
+
}
|
|
787
|
+
/**
|
|
788
|
+
* Serializes this context and all its steps to a plain object for SWML output.
|
|
789
|
+
* @returns A dictionary representation of this context.
|
|
790
|
+
*/
|
|
791
|
+
toDict() {
|
|
792
|
+
if (!this.steps.size)
|
|
793
|
+
throw new Error(`Context '${this.name}' has no steps defined`);
|
|
794
|
+
const d = {
|
|
795
|
+
steps: this.stepOrder.map((name) => this.steps.get(name).toDict()),
|
|
796
|
+
};
|
|
797
|
+
if (this._validContexts !== null)
|
|
798
|
+
d['valid_contexts'] = this._validContexts;
|
|
799
|
+
if (this._validSteps !== null)
|
|
800
|
+
d['valid_steps'] = this._validSteps;
|
|
801
|
+
if (this._initialStep !== null)
|
|
802
|
+
d['initial_step'] = this._initialStep;
|
|
803
|
+
if (this._postPrompt !== null)
|
|
804
|
+
d['post_prompt'] = this._postPrompt;
|
|
805
|
+
const sp = this.renderSystemPrompt();
|
|
806
|
+
if (sp !== null)
|
|
807
|
+
d['system_prompt'] = sp;
|
|
808
|
+
if (this._consolidate)
|
|
809
|
+
d['consolidate'] = true;
|
|
810
|
+
if (this._fullReset)
|
|
811
|
+
d['full_reset'] = true;
|
|
812
|
+
if (this._userPrompt !== null)
|
|
813
|
+
d['user_prompt'] = this._userPrompt;
|
|
814
|
+
if (this._isolated)
|
|
815
|
+
d['isolated'] = true;
|
|
816
|
+
if (this.promptSections.length) {
|
|
817
|
+
d['pom'] = this.promptSections;
|
|
818
|
+
}
|
|
819
|
+
else if (this.promptText !== null) {
|
|
820
|
+
d['prompt'] = this.promptText;
|
|
821
|
+
}
|
|
822
|
+
if (this._enterFillers)
|
|
823
|
+
d['enter_fillers'] = this._enterFillers;
|
|
824
|
+
if (this._exitFillers)
|
|
825
|
+
d['exit_fillers'] = this._exitFillers;
|
|
826
|
+
return d;
|
|
827
|
+
}
|
|
828
|
+
}
|
|
829
|
+
// ── ContextBuilder ──────────────────────────────────────────────────
|
|
830
|
+
/**
|
|
831
|
+
* Builder for multi-step, multi-context AI agent workflows.
|
|
832
|
+
*
|
|
833
|
+
* A ContextBuilder owns one or more Contexts; each Context owns an ordered
|
|
834
|
+
* list of Steps. Only one context and one step is active at a time. Per
|
|
835
|
+
* chat turn, the runtime injects the current step's instructions as a
|
|
836
|
+
* system message, then asks the LLM for a response.
|
|
837
|
+
*
|
|
838
|
+
* ## Native tools auto-injected by the runtime
|
|
839
|
+
*
|
|
840
|
+
* When a step (or its enclosing context) declares `validSteps` or
|
|
841
|
+
* `validContexts`, the runtime auto-injects two native tools so the model
|
|
842
|
+
* can navigate the flow:
|
|
843
|
+
*
|
|
844
|
+
* - `next_step(step: enum)` — present when validSteps is set
|
|
845
|
+
* - `change_context(context: enum)` — present when validContexts is set
|
|
846
|
+
*
|
|
847
|
+
* Their `enum` schemas are rewritten on every turn to match whatever
|
|
848
|
+
* validSteps / validContexts apply to the current step. You do NOT need
|
|
849
|
+
* to define these tools yourself; they appear automatically.
|
|
850
|
+
*
|
|
851
|
+
* A third native tool — `gather_submit` — is injected during gather_info
|
|
852
|
+
* questioning (see Step.setGatherInfo / addGatherQuestion).
|
|
853
|
+
*
|
|
854
|
+
* These three names — `next_step`, `change_context`, `gather_submit` —
|
|
855
|
+
* are reserved. ContextBuilder.validate() will reject any agent that
|
|
856
|
+
* defines a SWAIG tool with one of these names.
|
|
857
|
+
*
|
|
858
|
+
* ## Function whitelisting (Step.setFunctions)
|
|
859
|
+
*
|
|
860
|
+
* Each step may declare a `functions` whitelist. The whitelist is applied
|
|
861
|
+
* in-memory at the start of each LLM turn. CRITICALLY: if a step does NOT
|
|
862
|
+
* declare a `functions` field, it INHERITS the previous step's active set.
|
|
863
|
+
* See Step.setFunctions() for details and examples.
|
|
864
|
+
*
|
|
865
|
+
* ## Validation
|
|
866
|
+
*
|
|
867
|
+
* Call validate() (or toDict(), which calls it) to check that:
|
|
868
|
+
*
|
|
869
|
+
* - At least one context is defined
|
|
870
|
+
* - A single context must be named "default"
|
|
871
|
+
* - Every context has at least one step
|
|
872
|
+
* - validSteps references resolve to real step names (or "next")
|
|
873
|
+
* - validContexts references resolve to real context names
|
|
874
|
+
* - gather_info questions are non-empty and have unique keys
|
|
875
|
+
* - gather_info completion_action targets a reachable step
|
|
876
|
+
* - No user-defined SWAIG tool collides with a reserved native name
|
|
877
|
+
*
|
|
878
|
+
* @example Two-step support bot
|
|
879
|
+
* ```ts
|
|
880
|
+
* import { AgentBase, ContextBuilder } from '@signalwire/sdk';
|
|
881
|
+
*
|
|
882
|
+
* const agent = new AgentBase({ name: 'support', route: '/' });
|
|
883
|
+
*
|
|
884
|
+
* const contexts = new ContextBuilder();
|
|
885
|
+
* const flow = contexts.addContext('default');
|
|
886
|
+
*
|
|
887
|
+
* flow.addStep('greeting')
|
|
888
|
+
* .setText("Greet the caller and ask if they're an existing customer.")
|
|
889
|
+
* .setValidSteps(['existing', 'new']);
|
|
890
|
+
*
|
|
891
|
+
* flow.addStep('existing')
|
|
892
|
+
* .setText('Ask for the account number and read it back to confirm.');
|
|
893
|
+
*
|
|
894
|
+
* flow.addStep('new')
|
|
895
|
+
* .setText('Collect name, email, and reason for calling.');
|
|
896
|
+
*
|
|
897
|
+
* agent.defineContexts(contexts);
|
|
898
|
+
* ```
|
|
899
|
+
*
|
|
900
|
+
* @see {@link Context}
|
|
901
|
+
* @see {@link Step}
|
|
902
|
+
* @see {@link GatherInfo}
|
|
903
|
+
* @see {@link AgentBase.defineContexts}
|
|
904
|
+
*/
|
|
905
|
+
export class ContextBuilder {
|
|
906
|
+
contexts = new Map();
|
|
907
|
+
contextOrder = [];
|
|
908
|
+
agent = null;
|
|
909
|
+
/**
|
|
910
|
+
* Attach an agent reference so validate() can check user tool names
|
|
911
|
+
* against reserved native tool names. Called internally by
|
|
912
|
+
* AgentBase.defineContexts().
|
|
913
|
+
* @internal
|
|
914
|
+
*/
|
|
915
|
+
attachAgent(agent) {
|
|
916
|
+
this.agent = agent;
|
|
917
|
+
return this;
|
|
918
|
+
}
|
|
919
|
+
/**
|
|
920
|
+
* Removes all contexts, returning the builder to its initial state.
|
|
921
|
+
* Use this in a dynamic config callback when you need to rebuild
|
|
922
|
+
* contexts from scratch for a specific request.
|
|
923
|
+
* @returns This builder for chaining.
|
|
924
|
+
*/
|
|
925
|
+
reset() {
|
|
926
|
+
this.contexts.clear();
|
|
927
|
+
this.contextOrder = [];
|
|
928
|
+
return this;
|
|
929
|
+
}
|
|
930
|
+
/**
|
|
931
|
+
* Adds a new named context to the builder.
|
|
932
|
+
*
|
|
933
|
+
* @param name - The unique context name. A single-context flow must name
|
|
934
|
+
* its only context `"default"`.
|
|
935
|
+
* @returns The newly created {@link Context} for further configuration.
|
|
936
|
+
* @throws {Error} When the max-context limit is exceeded or a context with
|
|
937
|
+
* the same name already exists.
|
|
938
|
+
*/
|
|
939
|
+
addContext(name) {
|
|
940
|
+
if (this.contexts.size >= MAX_CONTEXTS) {
|
|
941
|
+
throw new Error(`Maximum number of contexts (${MAX_CONTEXTS}) exceeded`);
|
|
942
|
+
}
|
|
943
|
+
if (this.contexts.has(name))
|
|
944
|
+
throw new Error(`Context '${name}' already exists`);
|
|
945
|
+
const ctx = new Context(name);
|
|
946
|
+
this.contexts.set(name, ctx);
|
|
947
|
+
this.contextOrder.push(name);
|
|
948
|
+
return ctx;
|
|
949
|
+
}
|
|
950
|
+
/**
|
|
951
|
+
* Returns a context by name.
|
|
952
|
+
* @param name - The context name to retrieve.
|
|
953
|
+
* @returns The matching Context, or undefined if not found.
|
|
954
|
+
*/
|
|
955
|
+
getContext(name) {
|
|
956
|
+
return this.contexts.get(name);
|
|
957
|
+
}
|
|
958
|
+
/**
|
|
959
|
+
* Validates that all contexts have steps, naming constraints are met, and cross-context references are valid.
|
|
960
|
+
* @throws Error if validation fails.
|
|
961
|
+
*/
|
|
962
|
+
validate() {
|
|
963
|
+
if (!this.contexts.size)
|
|
964
|
+
throw new Error('At least one context must be defined');
|
|
965
|
+
if (this.contexts.size === 1) {
|
|
966
|
+
const name = [...this.contexts.keys()][0];
|
|
967
|
+
if (name !== 'default')
|
|
968
|
+
throw new Error("When using a single context, it must be named 'default'");
|
|
969
|
+
}
|
|
970
|
+
for (const [name, ctx] of this.contexts) {
|
|
971
|
+
if (!ctx.getSteps().size)
|
|
972
|
+
throw new Error(`Context '${name}' must have at least one step`);
|
|
973
|
+
}
|
|
974
|
+
// Validate initial_step references a real step in the context
|
|
975
|
+
for (const [name, ctx] of this.contexts) {
|
|
976
|
+
const initialStep = ctx.getInitialStep();
|
|
977
|
+
if (initialStep !== null && !ctx.getSteps().has(initialStep)) {
|
|
978
|
+
const available = [...ctx.getSteps().keys()].sort();
|
|
979
|
+
throw new Error(`Context '${name}' has initial_step='${initialStep}' but that step does not exist. ` +
|
|
980
|
+
`Available steps: [${available.map((n) => `'${n}'`).join(', ')}]`);
|
|
981
|
+
}
|
|
982
|
+
}
|
|
983
|
+
// Validate context references
|
|
984
|
+
for (const [, ctx] of this.contexts) {
|
|
985
|
+
const vc = ctx.getValidContexts();
|
|
986
|
+
if (vc) {
|
|
987
|
+
for (const ref of vc) {
|
|
988
|
+
if (!this.contexts.has(ref)) {
|
|
989
|
+
throw new Error(`Context '${ctx.name}' references unknown context '${ref}'`);
|
|
990
|
+
}
|
|
991
|
+
}
|
|
992
|
+
}
|
|
993
|
+
}
|
|
994
|
+
// Validate step references in valid_steps
|
|
995
|
+
for (const [ctxName, ctx] of this.contexts) {
|
|
996
|
+
const steps = ctx.getSteps();
|
|
997
|
+
for (const [stepName, step] of steps) {
|
|
998
|
+
const vs = step.getValidSteps();
|
|
999
|
+
if (vs) {
|
|
1000
|
+
for (const ref of vs) {
|
|
1001
|
+
if (ref !== 'next' && !steps.has(ref)) {
|
|
1002
|
+
throw new Error(`Step '${stepName}' in context '${ctxName}' references unknown step '${ref}'`);
|
|
1003
|
+
}
|
|
1004
|
+
}
|
|
1005
|
+
}
|
|
1006
|
+
}
|
|
1007
|
+
}
|
|
1008
|
+
// Validate context references in valid_contexts (step-level)
|
|
1009
|
+
for (const [ctxName, ctx] of this.contexts) {
|
|
1010
|
+
for (const [stepName, step] of ctx.getSteps()) {
|
|
1011
|
+
const vc = step.getStepValidContexts();
|
|
1012
|
+
if (vc) {
|
|
1013
|
+
for (const ref of vc) {
|
|
1014
|
+
if (!this.contexts.has(ref)) {
|
|
1015
|
+
throw new Error(`Step '${stepName}' in context '${ctxName}' references unknown context '${ref}'`);
|
|
1016
|
+
}
|
|
1017
|
+
}
|
|
1018
|
+
}
|
|
1019
|
+
}
|
|
1020
|
+
}
|
|
1021
|
+
// Validate gather_info: no duplicate question keys
|
|
1022
|
+
for (const [ctxName, ctx] of this.contexts) {
|
|
1023
|
+
for (const [stepName, step] of ctx.getSteps()) {
|
|
1024
|
+
const gi = step.getGatherInfo();
|
|
1025
|
+
if (!gi)
|
|
1026
|
+
continue;
|
|
1027
|
+
const keysSeen = new Set();
|
|
1028
|
+
for (const q of gi.getQuestions()) {
|
|
1029
|
+
if (keysSeen.has(q.key)) {
|
|
1030
|
+
throw new Error(`Step '${stepName}' in context '${ctxName}' has duplicate gather_info question key '${q.key}'`);
|
|
1031
|
+
}
|
|
1032
|
+
keysSeen.add(q.key);
|
|
1033
|
+
}
|
|
1034
|
+
}
|
|
1035
|
+
}
|
|
1036
|
+
// Validate completion_action references in gather_info
|
|
1037
|
+
for (const [ctxName, ctx] of this.contexts) {
|
|
1038
|
+
const stepOrder = ctx.getStepOrder();
|
|
1039
|
+
const steps = ctx.getSteps();
|
|
1040
|
+
for (let i = 0; i < stepOrder.length; i++) {
|
|
1041
|
+
const stepName = stepOrder[i];
|
|
1042
|
+
const step = steps.get(stepName);
|
|
1043
|
+
const gi = step.getGatherInfo();
|
|
1044
|
+
if (!gi)
|
|
1045
|
+
continue;
|
|
1046
|
+
const action = gi.getCompletionAction();
|
|
1047
|
+
if (!action)
|
|
1048
|
+
continue;
|
|
1049
|
+
if (action === 'next_step') {
|
|
1050
|
+
if (i === stepOrder.length - 1) {
|
|
1051
|
+
throw new Error(`Step '${stepName}' in context '${ctxName}' has gather_info ` +
|
|
1052
|
+
`completion_action='next_step' but it is the last step in the context. ` +
|
|
1053
|
+
`Either (1) add another step after '${stepName}', ` +
|
|
1054
|
+
`(2) set completion_action to the name of an existing step in this ` +
|
|
1055
|
+
`context to jump to it, or (3) omit completion_action (default) to ` +
|
|
1056
|
+
`stay in '${stepName}' after gathering completes.`);
|
|
1057
|
+
}
|
|
1058
|
+
}
|
|
1059
|
+
else if (!steps.has(action)) {
|
|
1060
|
+
const available = [...steps.keys()].sort();
|
|
1061
|
+
throw new Error(`Step '${stepName}' in context '${ctxName}' has gather_info ` +
|
|
1062
|
+
`completion_action='${action}' but '${action}' is not a step in this ` +
|
|
1063
|
+
`context. Valid options: 'next_step' (advance to the next sequential ` +
|
|
1064
|
+
`step), undefined (stay in the current step), or one of ` +
|
|
1065
|
+
`[${available.map((n) => `'${n}'`).join(', ')}].`);
|
|
1066
|
+
}
|
|
1067
|
+
}
|
|
1068
|
+
}
|
|
1069
|
+
// Validate that user-defined tools do not collide with reserved native
|
|
1070
|
+
// tool names. The runtime auto-injects next_step / change_context /
|
|
1071
|
+
// gather_submit when contexts/steps are present, so user tools sharing
|
|
1072
|
+
// those names would never be called.
|
|
1073
|
+
if (this.agent && typeof this.agent.getRegisteredTools === 'function') {
|
|
1074
|
+
const getRegisteredTools = this.agent.getRegisteredTools.bind(this.agent);
|
|
1075
|
+
const registered = getRegisteredTools();
|
|
1076
|
+
const colliding = [];
|
|
1077
|
+
for (const tool of registered) {
|
|
1078
|
+
if (tool && typeof tool.name === 'string' && RESERVED_NATIVE_TOOL_NAMES.has(tool.name)) {
|
|
1079
|
+
colliding.push(tool.name);
|
|
1080
|
+
}
|
|
1081
|
+
}
|
|
1082
|
+
colliding.sort();
|
|
1083
|
+
if (colliding.length > 0) {
|
|
1084
|
+
const reserved = [...RESERVED_NATIVE_TOOL_NAMES].sort();
|
|
1085
|
+
throw new Error(`Tool name(s) [${colliding.map((n) => `'${n}'`).join(', ')}] collide ` +
|
|
1086
|
+
`with reserved native tools auto-injected by contexts/steps. The ` +
|
|
1087
|
+
`names [${reserved.join(', ')}] are reserved and cannot be used ` +
|
|
1088
|
+
`for user-defined SWAIG tools when contexts/steps are in use. ` +
|
|
1089
|
+
`Rename your tool(s) to avoid the collision.`);
|
|
1090
|
+
}
|
|
1091
|
+
}
|
|
1092
|
+
}
|
|
1093
|
+
/**
|
|
1094
|
+
* Validates and serializes all contexts to a plain object for SWML output.
|
|
1095
|
+
* @returns A dictionary mapping context names to their serialized representations.
|
|
1096
|
+
*/
|
|
1097
|
+
toDict() {
|
|
1098
|
+
this.validate();
|
|
1099
|
+
const result = {};
|
|
1100
|
+
for (const name of this.contextOrder) {
|
|
1101
|
+
result[name] = this.contexts.get(name).toDict();
|
|
1102
|
+
}
|
|
1103
|
+
return result;
|
|
1104
|
+
}
|
|
1105
|
+
}
|
|
1106
|
+
// ── Helper ──────────────────────────────────────────────────────────
|
|
1107
|
+
/**
|
|
1108
|
+
* Creates a standalone Context instance without a ContextBuilder.
|
|
1109
|
+
* @param name - The context name (defaults to "default").
|
|
1110
|
+
* @returns A new Context instance.
|
|
1111
|
+
*/
|
|
1112
|
+
export function createSimpleContext(name = 'default') {
|
|
1113
|
+
return new Context(name);
|
|
1114
|
+
}
|
|
1115
|
+
//# sourceMappingURL=ContextBuilder.js.map
|