@signalwire/sdk 2.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.github/workflows/publish.yml +27 -0
- package/.github/workflows/test.yml +17 -0
- package/CLAUDE.md +112 -0
- package/README.md +254 -0
- package/docs/MIGRATION-2.0.md +81 -0
- package/docs/agent-guide.md +869 -0
- package/docs/agent_guide.md +1026 -0
- package/docs/api-reference.md +2420 -0
- package/docs/api_reference.md +1301 -0
- package/docs/architecture.md +843 -0
- package/docs/cli-guide.md +579 -0
- package/docs/cli_guide.md +448 -0
- package/docs/cloud_functions_guide.md +474 -0
- package/docs/configuration.md +422 -0
- package/docs/contexts-guide.md +787 -0
- package/docs/contexts_guide.md +511 -0
- package/docs/datamap-guide.md +1141 -0
- package/docs/datamap_guide.md +595 -0
- package/docs/llm_parameters.md +239 -0
- package/docs/mcp_gateway_reference.md +648 -0
- package/docs/mcp_integration.md +108 -0
- package/docs/prefabs-guide.md +800 -0
- package/docs/sdk_features.md +477 -0
- package/docs/security.md +436 -0
- package/docs/serverless-guide.md +513 -0
- package/docs/skills-guide.md +857 -0
- package/docs/skills-system.md +301 -0
- package/docs/skills_parameter_schema.md +392 -0
- package/docs/skills_system.md +467 -0
- package/docs/swaig-reference.md +1627 -0
- package/docs/swaig_reference.md +910 -0
- package/docs/swml_service_guide.md +600 -0
- package/docs/third_party_skills.md +533 -0
- package/docs/web_service.md +677 -0
- package/examples/README.md +131 -0
- package/examples/advanced-datamap.ts +100 -0
- package/examples/advanced-dynamic-config.ts +70 -0
- package/examples/auto-vivified.ts +94 -0
- package/examples/call-flow.ts +63 -0
- package/examples/comprehensive-dynamic.ts +125 -0
- package/examples/contexts-steps.ts +65 -0
- package/examples/custom-path.ts +45 -0
- package/examples/datamap-tools.ts +55 -0
- package/examples/datasphere-multi-instance.ts +63 -0
- package/examples/datasphere-serverless-env.ts +68 -0
- package/examples/datasphere-webhook-env.ts +66 -0
- package/examples/datasphere.ts +37 -0
- package/examples/declarative.ts +100 -0
- package/examples/dynamic-config.ts +54 -0
- package/examples/dynamic-info-gatherer.ts +69 -0
- package/examples/dynamic-swml-service.ts +67 -0
- package/examples/gather-info.ts +71 -0
- package/examples/gather-per-question-functions-demo.ts +140 -0
- package/examples/joke-agent.ts +34 -0
- package/examples/kubernetes-agent.ts +45 -0
- package/examples/llm-params.ts +69 -0
- package/examples/mcp-agent.ts +84 -0
- package/examples/mcp-gateway.ts +35 -0
- package/examples/multi-agent.ts +73 -0
- package/examples/multi-endpoint.ts +79 -0
- package/examples/pom-prompt.ts +71 -0
- package/examples/prefab-concierge.ts +47 -0
- package/examples/prefab-faq.ts +54 -0
- package/examples/prefab-info-gatherer.ts +33 -0
- package/examples/prefab-receptionist.ts +36 -0
- package/examples/prefab-survey.ts +68 -0
- package/examples/record-call.ts +67 -0
- package/examples/relay-demo.ts +33 -0
- package/examples/room-and-sip.ts +94 -0
- package/examples/serverless-lambda.ts +35 -0
- package/examples/session-state.ts +83 -0
- package/examples/simple-agent.ts +36 -0
- package/examples/simple-static.ts +29 -0
- package/examples/skills-demo.ts +38 -0
- package/examples/step-function-inheritance-demo.ts +124 -0
- package/examples/swaig-features.ts +187 -0
- package/examples/swml-service-routing.ts +66 -0
- package/examples/swml-service.ts +38 -0
- package/examples/tap.ts +68 -0
- package/examples/verb-methods.ts +45 -0
- package/examples/web-search-multi-instance.ts +72 -0
- package/examples/web-search.ts +38 -0
- package/examples/wikipedia.ts +36 -0
- package/livewire/README.md +140 -0
- package/livewire/docs/migration-guide.md +228 -0
- package/livewire/examples/livewire-basic-agent.ts +74 -0
- package/livewire/examples/livewire-handoff.ts +197 -0
- package/livewire/examples/livewire-multi-tool.ts +117 -0
- package/package.json +38 -0
- package/relay/README.md +70 -0
- package/relay/RELAY_IMPLEMENTATION_GUIDE.md +1257 -0
- package/relay/docs/call-methods.md +474 -0
- package/relay/docs/client-reference.md +142 -0
- package/relay/docs/events.md +134 -0
- package/relay/docs/getting-started.md +134 -0
- package/relay/docs/guide.md +306 -0
- package/relay/docs/messaging.md +182 -0
- package/relay/examples/relay-inbound.ts +66 -0
- package/relay/examples/relay-messaging.ts +71 -0
- package/relay/examples/relay-outbound.ts +76 -0
- package/rest/README.md +95 -0
- package/rest/docs/calling.md +273 -0
- package/rest/docs/client-reference.md +107 -0
- package/rest/docs/compat.md +204 -0
- package/rest/docs/fabric.md +183 -0
- package/rest/docs/getting-started.md +110 -0
- package/rest/docs/guide.md +351 -0
- package/rest/docs/namespaces.md +285 -0
- package/rest/examples/rest-10dlc-registration.ts +161 -0
- package/rest/examples/rest-calling-ivr-and-ai.ts +102 -0
- package/rest/examples/rest-calling-play-and-record.ts +91 -0
- package/rest/examples/rest-client.ts +65 -0
- package/rest/examples/rest-compat-laml.ts +210 -0
- package/rest/examples/rest-datasphere-search.ts +82 -0
- package/rest/examples/rest-fabric-conferences-and-routing.ts +144 -0
- package/rest/examples/rest-fabric-subscribers-and-sip.ts +108 -0
- package/rest/examples/rest-fabric-swml-and-callflows.ts +99 -0
- package/rest/examples/rest-manage-resources.ts +65 -0
- package/rest/examples/rest-phone-number-management.ts +197 -0
- package/rest/examples/rest-queues-mfa-and-recordings.ts +143 -0
- package/rest/examples/rest-video-rooms.ts +186 -0
- package/src/AgentBase.ts +2489 -0
- package/src/AgentServer.ts +415 -0
- package/src/AuthHandler.ts +256 -0
- package/src/ConfigLoader.ts +447 -0
- package/src/ContextBuilder.ts +1150 -0
- package/src/DataMap.ts +449 -0
- package/src/FunctionResult.ts +866 -0
- package/src/Logger.ts +337 -0
- package/src/PomBuilder.ts +439 -0
- package/src/PromptManager.ts +133 -0
- package/src/SWMLHandler.ts +298 -0
- package/src/SWMLService.ts +717 -0
- package/src/SchemaUtils.ts +361 -0
- package/src/SecurityUtils.ts +153 -0
- package/src/ServerlessAdapter.ts +221 -0
- package/src/SessionManager.ts +311 -0
- package/src/SslConfig.ts +118 -0
- package/src/SwaigFunction.ts +276 -0
- package/src/SwmlBuilder.ts +258 -0
- package/src/SwmlVerbMethods.generated.ts +234 -0
- package/src/TypeInference.ts +181 -0
- package/src/WebService.ts +619 -0
- package/src/cli/agent-loader.ts +166 -0
- package/src/cli/mock-data.ts +111 -0
- package/src/cli/swaig-test.ts +452 -0
- package/src/generateVerbTypes.ts +322 -0
- package/src/index.ts +167 -0
- package/src/livewire/index.ts +950 -0
- package/src/prefabs/ConciergeAgent.ts +287 -0
- package/src/prefabs/FAQBotAgent.ts +384 -0
- package/src/prefabs/InfoGathererAgent.ts +339 -0
- package/src/prefabs/ReceptionistAgent.ts +366 -0
- package/src/prefabs/SurveyAgent.ts +646 -0
- package/src/prefabs/index.ts +27 -0
- package/src/relay/Action.ts +314 -0
- package/src/relay/Call.ts +854 -0
- package/src/relay/Deferred.ts +71 -0
- package/src/relay/Message.ts +148 -0
- package/src/relay/RelayClient.ts +1036 -0
- package/src/relay/RelayError.ts +14 -0
- package/src/relay/RelayEvent.ts +892 -0
- package/src/relay/constants.ts +132 -0
- package/src/relay/index.ts +123 -0
- package/src/relay/types.ts +149 -0
- package/src/rest/HttpClient.ts +103 -0
- package/src/rest/RestError.ts +31 -0
- package/src/rest/base/BaseResource.ts +19 -0
- package/src/rest/base/CrudResource.ts +51 -0
- package/src/rest/base/CrudWithAddresses.ts +26 -0
- package/src/rest/index.ts +200 -0
- package/src/rest/namespaces/addresses.ts +32 -0
- package/src/rest/namespaces/calling.ts +187 -0
- package/src/rest/namespaces/chat.ts +20 -0
- package/src/rest/namespaces/compat.ts +352 -0
- package/src/rest/namespaces/datasphere.ts +45 -0
- package/src/rest/namespaces/fabric.ts +222 -0
- package/src/rest/namespaces/imported-numbers.ts +20 -0
- package/src/rest/namespaces/logs.ts +84 -0
- package/src/rest/namespaces/lookup.ts +21 -0
- package/src/rest/namespaces/mfa.ts +30 -0
- package/src/rest/namespaces/number-groups.ts +38 -0
- package/src/rest/namespaces/phone-numbers.ts +44 -0
- package/src/rest/namespaces/project.ts +36 -0
- package/src/rest/namespaces/pubsub.ts +20 -0
- package/src/rest/namespaces/queues.ts +33 -0
- package/src/rest/namespaces/recordings.ts +28 -0
- package/src/rest/namespaces/registry.ts +101 -0
- package/src/rest/namespaces/short-codes.ts +28 -0
- package/src/rest/namespaces/sip-profile.ts +25 -0
- package/src/rest/namespaces/verified-callers.ts +27 -0
- package/src/rest/namespaces/video.ts +165 -0
- package/src/rest/pagination.ts +84 -0
- package/src/rest/types.ts +61 -0
- package/src/schema.json +12250 -0
- package/src/skills/SkillBase.ts +547 -0
- package/src/skills/SkillManager.ts +415 -0
- package/src/skills/SkillRegistry.ts +367 -0
- package/src/skills/builtin/api_ninjas_trivia.ts +280 -0
- package/src/skills/builtin/ask_claude.ts +241 -0
- package/src/skills/builtin/claude_skills.ts +978 -0
- package/src/skills/builtin/custom_skills.ts +312 -0
- package/src/skills/builtin/datasphere.ts +438 -0
- package/src/skills/builtin/datasphere_serverless.ts +339 -0
- package/src/skills/builtin/datetime.ts +130 -0
- package/src/skills/builtin/google_maps.ts +651 -0
- package/src/skills/builtin/index.ts +88 -0
- package/src/skills/builtin/info_gatherer.ts +405 -0
- package/src/skills/builtin/joke.ts +191 -0
- package/src/skills/builtin/math.ts +142 -0
- package/src/skills/builtin/mcp_gateway.ts +677 -0
- package/src/skills/builtin/native_vector_search.ts +901 -0
- package/src/skills/builtin/play_background_file.ts +358 -0
- package/src/skills/builtin/spider.ts +869 -0
- package/src/skills/builtin/swml_transfer.ts +635 -0
- package/src/skills/builtin/weather_api.ts +248 -0
- package/src/skills/builtin/web_search.ts +1074 -0
- package/src/skills/builtin/wikipedia_search.ts +299 -0
- package/src/skills/index.ts +12 -0
- package/src/types.ts +132 -0
- package/tests/AgentBase.test.ts +1093 -0
- package/tests/AgentServer.test.ts +126 -0
- package/tests/AuthHandler.test.ts +133 -0
- package/tests/ConfigLoader.test.ts +151 -0
- package/tests/ContextBuilder.test.ts +108 -0
- package/tests/DataMap.test.ts +367 -0
- package/tests/EphemeralSkillCopy.test.ts +107 -0
- package/tests/FunctionResult.test.ts +298 -0
- package/tests/GracefulShutdown.test.ts +46 -0
- package/tests/Logger.test.ts +420 -0
- package/tests/PomBuilder.test.ts +228 -0
- package/tests/ProxyDetection.test.ts +228 -0
- package/tests/SWMLService.test.ts +320 -0
- package/tests/SWMLVerbHandler.test.ts +523 -0
- package/tests/SchemaUtils.test.ts +106 -0
- package/tests/SchemaUtils.verb.test.ts +206 -0
- package/tests/SecurityUtils.test.ts +192 -0
- package/tests/ServerlessAdapter.test.ts +222 -0
- package/tests/SessionManager.test.ts +257 -0
- package/tests/SkillBaseFeatures.test.ts +130 -0
- package/tests/SkillMultiInstance.test.ts +102 -0
- package/tests/SkillParameterSchemas.test.ts +134 -0
- package/tests/SkillRegistrySchema.test.ts +84 -0
- package/tests/SslConfig.test.ts +97 -0
- package/tests/SwmlBuilder.test.ts +400 -0
- package/tests/TypeInference.test.ts +165 -0
- package/tests/VerbHandlerRegistry.test.ts +128 -0
- package/tests/cli/mock-data.test.ts +113 -0
- package/tests/cli/swaig-test.test.ts +108 -0
- package/tests/examples.test.ts +194 -0
- package/tests/fixtures/scrape-parity/README.md +53 -0
- package/tests/fixtures/scrape-parity/expected/01_simple_article.json +5 -0
- package/tests/fixtures/scrape-parity/expected/02_class_based_noise.json +5 -0
- package/tests/fixtures/scrape-parity/expected/03_nested_containers.json +5 -0
- package/tests/fixtures/scrape-parity/expected/04_bare_body.json +5 -0
- package/tests/fixtures/scrape-parity/expected/05_malformed.json +5 -0
- package/tests/fixtures/scrape-parity/expected/06_multi_class.json +5 -0
- package/tests/fixtures/scrape-parity/expected/07_anchor_pattern.json +5 -0
- package/tests/fixtures/scrape-parity/expected/08_inline_script.json +5 -0
- package/tests/fixtures/scrape-parity/expected/09_whitespace_nbsp.json +5 -0
- package/tests/fixtures/scrape-parity/expected/10_entity_unicode.json +5 -0
- package/tests/fixtures/scrape-parity/expected/11_cdata_comments.json +5 -0
- package/tests/fixtures/scrape-parity/expected/12_deep_nested_removals.json +5 -0
- package/tests/fixtures/scrape-parity/html/01_simple_article.html +18 -0
- package/tests/fixtures/scrape-parity/html/02_class_based_noise.html +18 -0
- package/tests/fixtures/scrape-parity/html/03_nested_containers.html +13 -0
- package/tests/fixtures/scrape-parity/html/04_bare_body.html +9 -0
- package/tests/fixtures/scrape-parity/html/05_malformed.html +11 -0
- package/tests/fixtures/scrape-parity/html/06_multi_class.html +18 -0
- package/tests/fixtures/scrape-parity/html/07_anchor_pattern.html +12 -0
- package/tests/fixtures/scrape-parity/html/08_inline_script.html +17 -0
- package/tests/fixtures/scrape-parity/html/09_whitespace_nbsp.html +21 -0
- package/tests/fixtures/scrape-parity/html/10_entity_unicode.html +10 -0
- package/tests/fixtures/scrape-parity/html/11_cdata_comments.html +13 -0
- package/tests/fixtures/scrape-parity/html/12_deep_nested_removals.html +24 -0
- package/tests/fixtures/scrape-parity/python_extract.py +109 -0
- package/tests/livewire/livewire.test.ts +780 -0
- package/tests/mcp.test.ts +221 -0
- package/tests/prefabs/prefabs.test.ts +1093 -0
- package/tests/relay/Action.test.ts +392 -0
- package/tests/relay/Call.test.ts +535 -0
- package/tests/relay/Deferred.test.ts +71 -0
- package/tests/relay/Message.test.ts +164 -0
- package/tests/relay/RelayClient.test.ts +779 -0
- package/tests/relay/RelayEvent.test.ts +463 -0
- package/tests/relay/helpers.ts +79 -0
- package/tests/rest/HttpClient.test.ts +274 -0
- package/tests/rest/RestError.test.ts +53 -0
- package/tests/rest/calling.test.ts +156 -0
- package/tests/rest/client.test.ts +197 -0
- package/tests/rest/compat.test.ts +335 -0
- package/tests/rest/datasphere.test.ts +71 -0
- package/tests/rest/fabric.test.ts +186 -0
- package/tests/rest/helpers.ts +95 -0
- package/tests/rest/logs.test.ts +68 -0
- package/tests/rest/pagination.test.ts +133 -0
- package/tests/rest/registry.test.ts +94 -0
- package/tests/rest/relay-rest.test.ts +290 -0
- package/tests/rest/video.test.ts +173 -0
- package/tests/setup.ts +6 -0
- package/tests/skills/SkillBase.test.ts +108 -0
- package/tests/skills/SkillManager.test.ts +268 -0
- package/tests/skills/SkillRegistry.test.ts +176 -0
- package/tests/skills/builtin.test.ts +1472 -0
- package/tests/skills/claude-skills.test.ts +54 -0
- package/tests/skills/custom-skills.test.ts +53 -0
- package/tests/skills/datasphere-serverless.test.ts +70 -0
- package/tests/skills/datasphere.test.ts +107 -0
- package/tests/skills/datetime.test.ts +101 -0
- package/tests/skills/google-maps.test.ts +78 -0
- package/tests/skills/info-gatherer.test.ts +411 -0
- package/tests/skills/joke.test.ts +81 -0
- package/tests/skills/math.test.ts +68 -0
- package/tests/skills/mcp-gateway.test.ts +101 -0
- package/tests/skills/play-background.test.ts +54 -0
- package/tests/skills/spider.test.ts +108 -0
- package/tests/skills/swml-transfer.test.ts +178 -0
- package/tests/skills/trivia.test.ts +54 -0
- package/tests/skills/vector-search.test.ts +135 -0
- package/tests/skills/weather-api.test.ts +77 -0
- package/tests/skills/web-search-parity.test.ts +59 -0
- package/tests/skills/web-search.test.ts +103 -0
- package/tests/skills/wikipedia.test.ts +63 -0
- package/tsconfig.json +18 -0
- package/vitest.config.ts +9 -0
|
@@ -0,0 +1,950 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* LiveWire -- LiveKit-compatible agents powered by SignalWire.
|
|
3
|
+
*
|
|
4
|
+
* Provides the same class/function names as @livekit/agents-js so that
|
|
5
|
+
* developers can swap their import path and run on SignalWire's
|
|
6
|
+
* infrastructure. STT, TTS, VAD, LLM orchestration, and call control
|
|
7
|
+
* are all handled by SignalWire's control plane -- the noop'd options
|
|
8
|
+
* are accepted silently (logged once) to keep existing code compiling.
|
|
9
|
+
*/
|
|
10
|
+
|
|
11
|
+
import { AgentBase } from '../AgentBase.js';
|
|
12
|
+
import { FunctionResult } from '../FunctionResult.js';
|
|
13
|
+
import type { SwaigHandler } from '../SwaigFunction.js';
|
|
14
|
+
|
|
15
|
+
// ---------------------------------------------------------------------------
|
|
16
|
+
// Banner
|
|
17
|
+
// ---------------------------------------------------------------------------
|
|
18
|
+
|
|
19
|
+
const banner = `
|
|
20
|
+
__ _ _ ___
|
|
21
|
+
/ / (_) _____ | | / (_)_______
|
|
22
|
+
/ / / / | / / _ \\ | | /| / / / ___/ _ \\
|
|
23
|
+
/ /___/ /| |/ / __/ | |/ |/ / / / / __/
|
|
24
|
+
/_____/_/ |___/\\___/ |__/|__/_/_/ \\___/
|
|
25
|
+
|
|
26
|
+
LiveKit-compatible agents powered by SignalWire
|
|
27
|
+
`;
|
|
28
|
+
|
|
29
|
+
/** Print the ASCII banner to stderr, using ANSI cyan when stderr is a TTY. */
|
|
30
|
+
function printBanner(): void {
|
|
31
|
+
if (process.stderr.isTTY) {
|
|
32
|
+
process.stderr.write(`\x1b[36m${banner}\x1b[0m\n`);
|
|
33
|
+
} else {
|
|
34
|
+
process.stderr.write(`${banner}\n`);
|
|
35
|
+
}
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
// ---------------------------------------------------------------------------
|
|
39
|
+
// "Did You Know?" Tips
|
|
40
|
+
// ---------------------------------------------------------------------------
|
|
41
|
+
|
|
42
|
+
export const tips: string[] = [
|
|
43
|
+
"SignalWire agents support DataMap tools that execute server-side — no webhook infrastructure needed. See: docs/datamap-guide.md",
|
|
44
|
+
"SignalWire Contexts & Steps give you mechanical state control over conversations — no prompt engineering needed. See: docs/contexts-guide.md",
|
|
45
|
+
"SignalWire agents can transfer calls between agents with a single SwmlTransfer() action",
|
|
46
|
+
"SignalWire handles 18 built-in skills (datetime, math, web search, etc.) with one-liner integration via agent.addSkill()",
|
|
47
|
+
"SignalWire agents support SMS, conferencing, call recording, and SIP — all from the same agent",
|
|
48
|
+
"Your agent's entire AI pipeline (STT, LLM, TTS, VAD) runs in SignalWire's cloud — zero infrastructure to manage",
|
|
49
|
+
"SignalWire prefab agents (Survey, Receptionist, FAQ, Concierge) give you production patterns in 10 lines of code",
|
|
50
|
+
"SignalWire's RELAY client gives you real-time WebSocket call control with 57+ methods — play, record, detect, conference, and more",
|
|
51
|
+
"SignalWire agents auto-generate SWML documents — the platform handles media, turn detection, and barge-in for you",
|
|
52
|
+
"You can host multiple agents on one server with AgentServer — each with its own route, prompt, and tools",
|
|
53
|
+
];
|
|
54
|
+
|
|
55
|
+
function printTip(): void {
|
|
56
|
+
const tip = tips[Math.floor(Math.random() * tips.length)];
|
|
57
|
+
process.stderr.write(`\n\u{1f4a1} Did you know? ${tip}\n\n`);
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
// ---------------------------------------------------------------------------
|
|
61
|
+
// Noop logging helpers
|
|
62
|
+
// ---------------------------------------------------------------------------
|
|
63
|
+
|
|
64
|
+
/**
|
|
65
|
+
* NoopTracker ensures each informational message is logged at most once,
|
|
66
|
+
* preventing spam when the same noop path is exercised repeatedly.
|
|
67
|
+
*/
|
|
68
|
+
class NoopTracker {
|
|
69
|
+
private logged = new Set<string>();
|
|
70
|
+
|
|
71
|
+
once(key: string, message: string): void {
|
|
72
|
+
if (this.logged.has(key)) return;
|
|
73
|
+
this.logged.add(key);
|
|
74
|
+
process.stderr.write(`[LiveWire] ${message}\n`);
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
/** Expose whether a key has been logged (for testing). */
|
|
78
|
+
hasLogged(key: string): boolean {
|
|
79
|
+
return this.logged.has(key);
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
/** Reset all tracked keys (for testing). */
|
|
83
|
+
reset(): void {
|
|
84
|
+
this.logged.clear();
|
|
85
|
+
}
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
const globalNoop = new NoopTracker();
|
|
89
|
+
|
|
90
|
+
// Re-export for testing
|
|
91
|
+
export { NoopTracker, globalNoop };
|
|
92
|
+
|
|
93
|
+
// ---------------------------------------------------------------------------
|
|
94
|
+
// VoiceOptions
|
|
95
|
+
// ---------------------------------------------------------------------------
|
|
96
|
+
|
|
97
|
+
/** Voice configuration options passed through to the SignalWire AI config. */
|
|
98
|
+
export interface VoiceOptions {
|
|
99
|
+
voice: string;
|
|
100
|
+
engine: string;
|
|
101
|
+
language: string;
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
// ---------------------------------------------------------------------------
|
|
105
|
+
// FunctionTool
|
|
106
|
+
// ---------------------------------------------------------------------------
|
|
107
|
+
|
|
108
|
+
/** A tool definition that can be registered on an Agent. */
|
|
109
|
+
export interface FunctionTool {
|
|
110
|
+
name: string;
|
|
111
|
+
description: string;
|
|
112
|
+
parameters?: Record<string, unknown>;
|
|
113
|
+
execute: (params: any, context: { ctx: RunContext }) => any;
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
// ---------------------------------------------------------------------------
|
|
117
|
+
// Agent
|
|
118
|
+
// ---------------------------------------------------------------------------
|
|
119
|
+
|
|
120
|
+
/** Mirrors a LiveKit voice.Agent -- holds instructions and tool definitions. */
|
|
121
|
+
export class Agent<UserData = any> {
|
|
122
|
+
instructions: string;
|
|
123
|
+
tools: Record<string, FunctionTool>;
|
|
124
|
+
userData?: UserData;
|
|
125
|
+
|
|
126
|
+
/** @internal Pipeline hint stored for AgentSession mapping. */
|
|
127
|
+
_llmHint: unknown;
|
|
128
|
+
/** @internal */
|
|
129
|
+
_allowInterruptions: unknown;
|
|
130
|
+
/** @internal */
|
|
131
|
+
_minEndpointingDelay: unknown;
|
|
132
|
+
/** @internal */
|
|
133
|
+
_maxEndpointingDelay: unknown;
|
|
134
|
+
|
|
135
|
+
private _session?: AgentSession<UserData>;
|
|
136
|
+
|
|
137
|
+
constructor(options?: {
|
|
138
|
+
instructions?: string;
|
|
139
|
+
tools?: FunctionTool[];
|
|
140
|
+
userData?: UserData;
|
|
141
|
+
chatCtx?: unknown;
|
|
142
|
+
stt?: unknown;
|
|
143
|
+
tts?: unknown;
|
|
144
|
+
llm?: unknown;
|
|
145
|
+
vad?: unknown;
|
|
146
|
+
turnDetection?: unknown;
|
|
147
|
+
mcpServers?: unknown;
|
|
148
|
+
allowInterruptions?: boolean;
|
|
149
|
+
minEndpointingDelay?: number;
|
|
150
|
+
maxEndpointingDelay?: number;
|
|
151
|
+
}) {
|
|
152
|
+
this.instructions = options?.instructions ?? '';
|
|
153
|
+
// Mirror Python: tools is Optional[List[Any]], stored internally as a name-keyed map.
|
|
154
|
+
// Build the record from the array using the same pattern as updateTools().
|
|
155
|
+
if (options?.tools) {
|
|
156
|
+
const record: Record<string, FunctionTool> = {};
|
|
157
|
+
for (const t of options.tools) {
|
|
158
|
+
record[t.name] = t;
|
|
159
|
+
}
|
|
160
|
+
this.tools = record;
|
|
161
|
+
} else {
|
|
162
|
+
this.tools = {};
|
|
163
|
+
}
|
|
164
|
+
this.userData = options?.userData;
|
|
165
|
+
|
|
166
|
+
// Pipeline noop advisories (matching Python behavior)
|
|
167
|
+
if (options?.stt != null) {
|
|
168
|
+
globalNoop.once(
|
|
169
|
+
'agent_stt',
|
|
170
|
+
"Agent(stt=...): SignalWire's control plane handles speech recognition at scale -- no configuration needed",
|
|
171
|
+
);
|
|
172
|
+
}
|
|
173
|
+
if (options?.tts != null) {
|
|
174
|
+
globalNoop.once(
|
|
175
|
+
'agent_tts',
|
|
176
|
+
"Agent(tts=...): SignalWire's control plane handles text-to-speech at scale -- no configuration needed",
|
|
177
|
+
);
|
|
178
|
+
}
|
|
179
|
+
if (options?.vad != null) {
|
|
180
|
+
globalNoop.once(
|
|
181
|
+
'agent_vad',
|
|
182
|
+
"Agent(vad=...): SignalWire's control plane handles voice activity detection at scale automatically",
|
|
183
|
+
);
|
|
184
|
+
}
|
|
185
|
+
if (options?.turnDetection != null) {
|
|
186
|
+
globalNoop.once(
|
|
187
|
+
'agent_turn_detection',
|
|
188
|
+
"Agent(turnDetection=...): SignalWire's control plane handles turn detection at scale automatically",
|
|
189
|
+
);
|
|
190
|
+
}
|
|
191
|
+
if (options?.mcpServers != null) {
|
|
192
|
+
globalNoop.once(
|
|
193
|
+
'agent_mcp_servers',
|
|
194
|
+
'Agent(mcpServers=...): MCP servers are not yet supported in LiveWire -- tools should be registered via tool()',
|
|
195
|
+
);
|
|
196
|
+
}
|
|
197
|
+
|
|
198
|
+
// Store pipeline hints for later mapping (used by AgentSession.start)
|
|
199
|
+
this._llmHint = options?.llm;
|
|
200
|
+
this._allowInterruptions = options?.allowInterruptions;
|
|
201
|
+
this._minEndpointingDelay = options?.minEndpointingDelay;
|
|
202
|
+
this._maxEndpointingDelay = options?.maxEndpointingDelay;
|
|
203
|
+
}
|
|
204
|
+
|
|
205
|
+
// ------------------------------------------------------------------
|
|
206
|
+
// session property
|
|
207
|
+
// ------------------------------------------------------------------
|
|
208
|
+
|
|
209
|
+
get session(): AgentSession<UserData> | undefined {
|
|
210
|
+
return this._session;
|
|
211
|
+
}
|
|
212
|
+
|
|
213
|
+
set session(value: AgentSession<UserData> | undefined) {
|
|
214
|
+
this._session = value;
|
|
215
|
+
}
|
|
216
|
+
|
|
217
|
+
// ------------------------------------------------------------------
|
|
218
|
+
// Lifecycle hooks (override in subclass)
|
|
219
|
+
// ------------------------------------------------------------------
|
|
220
|
+
|
|
221
|
+
/** Called when the agent enters. Override in subclass. */
|
|
222
|
+
async onEnter(): Promise<void> {}
|
|
223
|
+
|
|
224
|
+
/** Called when the agent exits. Override in subclass. */
|
|
225
|
+
async onExit(): Promise<void> {}
|
|
226
|
+
|
|
227
|
+
/** Called when the user finishes speaking. Override in subclass. */
|
|
228
|
+
async onUserTurnCompleted(_turnCtx?: unknown, _newMessage?: unknown): Promise<void> {}
|
|
229
|
+
|
|
230
|
+
// ------------------------------------------------------------------
|
|
231
|
+
// Pipeline nodes -- all noop + log (SignalWire handles these)
|
|
232
|
+
// ------------------------------------------------------------------
|
|
233
|
+
|
|
234
|
+
/** Noop -- SignalWire handles STT in its control plane. */
|
|
235
|
+
async sttNode(_audio?: unknown, _modelSettings?: unknown): Promise<void> {
|
|
236
|
+
globalNoop.once(
|
|
237
|
+
'stt_node',
|
|
238
|
+
"Agent.sttNode(): SignalWire's control plane handles speech recognition -- this node is a no-op",
|
|
239
|
+
);
|
|
240
|
+
}
|
|
241
|
+
|
|
242
|
+
/** Noop -- SignalWire handles LLM in its control plane. */
|
|
243
|
+
async llmNode(_chatCtx?: unknown, _tools?: unknown, _modelSettings?: unknown): Promise<void> {
|
|
244
|
+
globalNoop.once(
|
|
245
|
+
'llm_node',
|
|
246
|
+
"Agent.llmNode(): SignalWire's control plane handles LLM inference -- this node is a no-op",
|
|
247
|
+
);
|
|
248
|
+
}
|
|
249
|
+
|
|
250
|
+
/** Noop -- SignalWire handles TTS in its control plane. */
|
|
251
|
+
async ttsNode(_text?: unknown, _modelSettings?: unknown): Promise<void> {
|
|
252
|
+
globalNoop.once(
|
|
253
|
+
'tts_node',
|
|
254
|
+
"Agent.ttsNode(): SignalWire's control plane handles text-to-speech -- this node is a no-op",
|
|
255
|
+
);
|
|
256
|
+
}
|
|
257
|
+
|
|
258
|
+
// ------------------------------------------------------------------
|
|
259
|
+
// Dynamic updates
|
|
260
|
+
// ------------------------------------------------------------------
|
|
261
|
+
|
|
262
|
+
/** Update the agent's instructions mid-session. */
|
|
263
|
+
async updateInstructions(instructions: string): Promise<void> {
|
|
264
|
+
this.instructions = instructions;
|
|
265
|
+
}
|
|
266
|
+
|
|
267
|
+
/** Update the agent's tool list mid-session. */
|
|
268
|
+
async updateTools(tools: FunctionTool[]): Promise<void> {
|
|
269
|
+
const record: Record<string, FunctionTool> = {};
|
|
270
|
+
for (const t of tools) {
|
|
271
|
+
record[t.name] = t;
|
|
272
|
+
}
|
|
273
|
+
this.tools = record;
|
|
274
|
+
}
|
|
275
|
+
}
|
|
276
|
+
|
|
277
|
+
// ---------------------------------------------------------------------------
|
|
278
|
+
// RunContext
|
|
279
|
+
// ---------------------------------------------------------------------------
|
|
280
|
+
|
|
281
|
+
/** Mirrors a LiveKit RunContext -- available inside tool handlers. */
|
|
282
|
+
export class RunContext<UserData = any> {
|
|
283
|
+
session?: AgentSession<UserData>;
|
|
284
|
+
speechHandle?: unknown;
|
|
285
|
+
functionCall?: unknown;
|
|
286
|
+
|
|
287
|
+
constructor(
|
|
288
|
+
session?: AgentSession<UserData>,
|
|
289
|
+
options?: { speechHandle?: unknown; functionCall?: unknown },
|
|
290
|
+
) {
|
|
291
|
+
this.session = session;
|
|
292
|
+
this.speechHandle = options?.speechHandle;
|
|
293
|
+
this.functionCall = options?.functionCall;
|
|
294
|
+
}
|
|
295
|
+
|
|
296
|
+
get userData(): UserData {
|
|
297
|
+
return (this.session?.userData ?? {}) as UserData;
|
|
298
|
+
}
|
|
299
|
+
}
|
|
300
|
+
|
|
301
|
+
// ---------------------------------------------------------------------------
|
|
302
|
+
// AgentSession
|
|
303
|
+
// ---------------------------------------------------------------------------
|
|
304
|
+
|
|
305
|
+
/** Mirrors a LiveKit AgentSession -- binds an Agent to SignalWire. */
|
|
306
|
+
export class AgentSession<UserData = any> {
|
|
307
|
+
private _llm: any;
|
|
308
|
+
private _tools: FunctionTool[];
|
|
309
|
+
private _userData: UserData;
|
|
310
|
+
private _agent?: Agent<UserData>;
|
|
311
|
+
private _swAgent?: AgentBase;
|
|
312
|
+
private _allowInterruptions: boolean;
|
|
313
|
+
private _minInterruptionDuration: number;
|
|
314
|
+
private _minEndpointingDelay: number;
|
|
315
|
+
private _maxEndpointingDelay: number;
|
|
316
|
+
private _maxToolSteps: number;
|
|
317
|
+
private _preemptiveGeneration: boolean;
|
|
318
|
+
private _history: Array<Record<string, string>> = [];
|
|
319
|
+
private _sayQueue: string[] = [];
|
|
320
|
+
private noop = new NoopTracker();
|
|
321
|
+
|
|
322
|
+
constructor(options?: {
|
|
323
|
+
stt?: any;
|
|
324
|
+
tts?: any;
|
|
325
|
+
llm?: any;
|
|
326
|
+
vad?: any;
|
|
327
|
+
turnDetection?: any;
|
|
328
|
+
tools?: FunctionTool[];
|
|
329
|
+
mcpServers?: unknown;
|
|
330
|
+
userData?: UserData;
|
|
331
|
+
allowInterruptions?: boolean;
|
|
332
|
+
minInterruptionDuration?: number;
|
|
333
|
+
minEndpointingDelay?: number;
|
|
334
|
+
maxEndpointingDelay?: number;
|
|
335
|
+
maxToolSteps?: number;
|
|
336
|
+
preemptiveGeneration?: boolean;
|
|
337
|
+
}) {
|
|
338
|
+
this._llm = options?.llm;
|
|
339
|
+
this._tools = options?.tools ? [...options.tools] : [];
|
|
340
|
+
this._userData = (options?.userData ?? {}) as UserData;
|
|
341
|
+
this._allowInterruptions = options?.allowInterruptions ?? true;
|
|
342
|
+
this._minInterruptionDuration = options?.minInterruptionDuration ?? 0.5;
|
|
343
|
+
this._minEndpointingDelay = options?.minEndpointingDelay ?? 0.5;
|
|
344
|
+
this._maxEndpointingDelay = options?.maxEndpointingDelay ?? 3.0;
|
|
345
|
+
this._maxToolSteps = options?.maxToolSteps ?? 3;
|
|
346
|
+
this._preemptiveGeneration = options?.preemptiveGeneration ?? false;
|
|
347
|
+
|
|
348
|
+
if (options?.stt != null) {
|
|
349
|
+
this.noop.once(
|
|
350
|
+
'stt',
|
|
351
|
+
`WithSTT("${options.stt}"): SignalWire's control plane handles speech recognition at scale — no configuration needed`,
|
|
352
|
+
);
|
|
353
|
+
}
|
|
354
|
+
if (options?.tts != null) {
|
|
355
|
+
this.noop.once(
|
|
356
|
+
'tts',
|
|
357
|
+
`WithTTS("${options.tts}"): SignalWire's control plane handles text-to-speech at scale — no configuration needed`,
|
|
358
|
+
);
|
|
359
|
+
}
|
|
360
|
+
if (options?.vad != null) {
|
|
361
|
+
this.noop.once(
|
|
362
|
+
'vad',
|
|
363
|
+
"WithVAD(): SignalWire's control plane handles voice activity detection at scale automatically",
|
|
364
|
+
);
|
|
365
|
+
}
|
|
366
|
+
if (options?.turnDetection != null) {
|
|
367
|
+
this.noop.once(
|
|
368
|
+
'turn_detection',
|
|
369
|
+
`WithTurnDetection("${options.turnDetection}"): SignalWire's control plane handles turn detection at scale automatically`,
|
|
370
|
+
);
|
|
371
|
+
}
|
|
372
|
+
if (options?.mcpServers != null) {
|
|
373
|
+
this.noop.once(
|
|
374
|
+
'mcp_servers',
|
|
375
|
+
'AgentSession(mcpServers=...): MCP servers are not yet supported in LiveWire -- tools should be registered via tool()',
|
|
376
|
+
);
|
|
377
|
+
}
|
|
378
|
+
if (options?.maxToolSteps != null && options.maxToolSteps !== 3) {
|
|
379
|
+
this.noop.once(
|
|
380
|
+
'max_tool_steps',
|
|
381
|
+
`AgentSession(maxToolSteps=${options.maxToolSteps}): SignalWire's control plane handles tool execution depth at scale automatically`,
|
|
382
|
+
);
|
|
383
|
+
}
|
|
384
|
+
}
|
|
385
|
+
|
|
386
|
+
/** Start the session by binding the agent to a SignalWire AgentBase. */
|
|
387
|
+
async start(params: { agent: Agent<UserData>; room?: any; record?: boolean }): Promise<void> {
|
|
388
|
+
this._agent = params.agent;
|
|
389
|
+
params.agent.session = this;
|
|
390
|
+
|
|
391
|
+
// Mirrors Python _build_sw_agent(): alias self._agent for subsequent reads
|
|
392
|
+
const agent = this._agent;
|
|
393
|
+
|
|
394
|
+
// Build a real SignalWire AgentBase
|
|
395
|
+
const swAgent = new AgentBase({
|
|
396
|
+
name: 'LiveWireAgent',
|
|
397
|
+
route: '/',
|
|
398
|
+
});
|
|
399
|
+
|
|
400
|
+
swAgent.setPromptText(agent.instructions);
|
|
401
|
+
|
|
402
|
+
// Map LLM model if provided (session-level takes priority, then agent-level hint)
|
|
403
|
+
const llmModel = this._llm ?? agent._llmHint;
|
|
404
|
+
if (llmModel != null) {
|
|
405
|
+
let model = String(llmModel);
|
|
406
|
+
const slashIdx = model.indexOf('/');
|
|
407
|
+
if (slashIdx >= 0) model = model.slice(slashIdx + 1);
|
|
408
|
+
swAgent.setParam('model', model);
|
|
409
|
+
}
|
|
410
|
+
|
|
411
|
+
// Map interruption / barge settings
|
|
412
|
+
let allowInterruptions = this._allowInterruptions;
|
|
413
|
+
if (agent._allowInterruptions != null) {
|
|
414
|
+
allowInterruptions = agent._allowInterruptions as boolean;
|
|
415
|
+
}
|
|
416
|
+
if (!allowInterruptions) {
|
|
417
|
+
swAgent.setParam('barge_confidence', 1.0);
|
|
418
|
+
}
|
|
419
|
+
|
|
420
|
+
// Map endpointing delays
|
|
421
|
+
let minEp: number = this._minEndpointingDelay;
|
|
422
|
+
if (agent._minEndpointingDelay != null) {
|
|
423
|
+
minEp = agent._minEndpointingDelay as number;
|
|
424
|
+
}
|
|
425
|
+
if (minEp > 0) {
|
|
426
|
+
swAgent.setParam('end_of_speech_timeout', Math.round(minEp * 1000));
|
|
427
|
+
}
|
|
428
|
+
|
|
429
|
+
let maxEp: number = this._maxEndpointingDelay;
|
|
430
|
+
if (agent._maxEndpointingDelay != null) {
|
|
431
|
+
maxEp = agent._maxEndpointingDelay as number;
|
|
432
|
+
}
|
|
433
|
+
if (maxEp > 0) {
|
|
434
|
+
swAgent.setParam('attention_timeout', Math.round(maxEp * 1000));
|
|
435
|
+
}
|
|
436
|
+
|
|
437
|
+
// Register all tools from the agent + session-level tools
|
|
438
|
+
const allTools: [string, FunctionTool][] = [
|
|
439
|
+
...Object.entries(agent.tools),
|
|
440
|
+
...this._tools.map((t) => [t.name, t] as [string, FunctionTool]),
|
|
441
|
+
];
|
|
442
|
+
for (const [name, toolDef] of allTools) {
|
|
443
|
+
const handler: SwaigHandler = async (args, _rawData) => {
|
|
444
|
+
const ctx = new RunContext<UserData>(this);
|
|
445
|
+
const result = await toolDef.execute(args, { ctx });
|
|
446
|
+
if (result instanceof FunctionResult) return result;
|
|
447
|
+
if (typeof result === 'string') return new FunctionResult(result);
|
|
448
|
+
return new FunctionResult(JSON.stringify(result));
|
|
449
|
+
};
|
|
450
|
+
swAgent.defineTool({
|
|
451
|
+
name,
|
|
452
|
+
description: toolDef.description,
|
|
453
|
+
parameters: toolDef.parameters,
|
|
454
|
+
handler,
|
|
455
|
+
});
|
|
456
|
+
}
|
|
457
|
+
|
|
458
|
+
// Initial greeting (say queue)
|
|
459
|
+
for (const text of this._sayQueue) {
|
|
460
|
+
swAgent.promptAddSection('Initial Greeting', { body: text });
|
|
461
|
+
}
|
|
462
|
+
|
|
463
|
+
this._swAgent = swAgent;
|
|
464
|
+
}
|
|
465
|
+
|
|
466
|
+
/** Queue text to be spoken by the agent. */
|
|
467
|
+
say(text: string): void {
|
|
468
|
+
// If the session is already started, inject directly into the SWML flow.
|
|
469
|
+
// Otherwise queue the text so it is replayed when start() is called.
|
|
470
|
+
if (this._swAgent) {
|
|
471
|
+
this._swAgent.promptAddSection('Say', { body: text });
|
|
472
|
+
} else {
|
|
473
|
+
this._sayQueue.push(text);
|
|
474
|
+
}
|
|
475
|
+
}
|
|
476
|
+
|
|
477
|
+
/** Trigger the agent to generate a reply, optionally with extra instructions. */
|
|
478
|
+
generateReply(options?: { instructions?: string }): void {
|
|
479
|
+
if (options?.instructions && this._swAgent) {
|
|
480
|
+
this._swAgent.promptAddSection('Initial Greeting', { body: options.instructions });
|
|
481
|
+
}
|
|
482
|
+
}
|
|
483
|
+
|
|
484
|
+
/** Interrupt current speech -- noop on SignalWire (barge-in is automatic). */
|
|
485
|
+
interrupt(): void {
|
|
486
|
+
this.noop.once('interrupt', "Interrupt(): SignalWire handles barge-in automatically via its control plane");
|
|
487
|
+
}
|
|
488
|
+
|
|
489
|
+
/** Update the agent bound to this session. */
|
|
490
|
+
updateAgent(agent: Agent<UserData>): void {
|
|
491
|
+
this._agent = agent;
|
|
492
|
+
agent.session = this;
|
|
493
|
+
if (this._swAgent) {
|
|
494
|
+
this._swAgent.setPromptText(agent.instructions);
|
|
495
|
+
}
|
|
496
|
+
}
|
|
497
|
+
|
|
498
|
+
get userData(): UserData {
|
|
499
|
+
return this._userData;
|
|
500
|
+
}
|
|
501
|
+
|
|
502
|
+
set userData(val: UserData) {
|
|
503
|
+
this._userData = val;
|
|
504
|
+
}
|
|
505
|
+
|
|
506
|
+
/** Conversation history entries. */
|
|
507
|
+
get history(): Array<Record<string, string>> {
|
|
508
|
+
return this._history;
|
|
509
|
+
}
|
|
510
|
+
|
|
511
|
+
/** Return the underlying SignalWire AgentBase (for testing / advanced use). */
|
|
512
|
+
getSwAgent(): AgentBase | undefined {
|
|
513
|
+
return this._swAgent;
|
|
514
|
+
}
|
|
515
|
+
}
|
|
516
|
+
|
|
517
|
+
// ---------------------------------------------------------------------------
|
|
518
|
+
// tool()
|
|
519
|
+
// ---------------------------------------------------------------------------
|
|
520
|
+
|
|
521
|
+
/**
|
|
522
|
+
* Create a tool definition -- mirrors llm.tool() from @livekit/agents-js.
|
|
523
|
+
* Accepts a description, optional parameters (Zod or JSON schema), and an
|
|
524
|
+
* execute function.
|
|
525
|
+
*/
|
|
526
|
+
export function tool<P = any>(options: {
|
|
527
|
+
description: string;
|
|
528
|
+
parameters?: any;
|
|
529
|
+
execute: (params: P, context: { ctx: RunContext }) => any;
|
|
530
|
+
}): FunctionTool {
|
|
531
|
+
// Extract JSON schema from parameters if provided
|
|
532
|
+
let jsonSchema: Record<string, unknown> | undefined;
|
|
533
|
+
if (options.parameters) {
|
|
534
|
+
// If it looks like a Zod schema (has a .shape or ._def), try to extract
|
|
535
|
+
if (typeof options.parameters === 'object' && options.parameters._def) {
|
|
536
|
+
// Best-effort Zod extraction -- store as-is for now
|
|
537
|
+
jsonSchema = options.parameters;
|
|
538
|
+
} else {
|
|
539
|
+
jsonSchema = options.parameters;
|
|
540
|
+
}
|
|
541
|
+
}
|
|
542
|
+
|
|
543
|
+
return {
|
|
544
|
+
name: '', // Filled in when assigned to agent.tools
|
|
545
|
+
description: options.description,
|
|
546
|
+
parameters: jsonSchema,
|
|
547
|
+
execute: options.execute,
|
|
548
|
+
};
|
|
549
|
+
}
|
|
550
|
+
|
|
551
|
+
// ---------------------------------------------------------------------------
|
|
552
|
+
// handoff()
|
|
553
|
+
// ---------------------------------------------------------------------------
|
|
554
|
+
|
|
555
|
+
/** Create an AgentHandoff descriptor for multi-agent scenarios. */
|
|
556
|
+
export function handoff(options: { agent: Agent; returns?: string }): AgentHandoff {
|
|
557
|
+
const h = new AgentHandoff();
|
|
558
|
+
h.agent = options.agent;
|
|
559
|
+
h.returns = options.returns;
|
|
560
|
+
return h;
|
|
561
|
+
}
|
|
562
|
+
|
|
563
|
+
// ---------------------------------------------------------------------------
|
|
564
|
+
// AgentHandoff / StopResponse / ToolError
|
|
565
|
+
// ---------------------------------------------------------------------------
|
|
566
|
+
|
|
567
|
+
/** Signals a handoff to another agent in multi-agent scenarios. */
|
|
568
|
+
export class AgentHandoff {
|
|
569
|
+
agent!: Agent;
|
|
570
|
+
returns?: string;
|
|
571
|
+
}
|
|
572
|
+
|
|
573
|
+
/** Signals that a tool should not trigger another LLM reply. */
|
|
574
|
+
export class StopResponse extends Error {
|
|
575
|
+
constructor(message?: string) {
|
|
576
|
+
super(message ?? 'StopResponse');
|
|
577
|
+
this.name = 'StopResponse';
|
|
578
|
+
}
|
|
579
|
+
}
|
|
580
|
+
|
|
581
|
+
/** Error thrown from a tool to signal failure back to the LLM. */
|
|
582
|
+
export class ToolError extends Error {
|
|
583
|
+
constructor(message: string) {
|
|
584
|
+
super(message);
|
|
585
|
+
this.name = 'ToolError';
|
|
586
|
+
}
|
|
587
|
+
}
|
|
588
|
+
|
|
589
|
+
// ---------------------------------------------------------------------------
|
|
590
|
+
// JobProcess
|
|
591
|
+
// ---------------------------------------------------------------------------
|
|
592
|
+
|
|
593
|
+
/** Mirrors a LiveKit JobProcess -- used for prewarm/setup. */
|
|
594
|
+
export class JobProcess {
|
|
595
|
+
userData: Record<string, any> = {};
|
|
596
|
+
}
|
|
597
|
+
|
|
598
|
+
// ---------------------------------------------------------------------------
|
|
599
|
+
// Room
|
|
600
|
+
// ---------------------------------------------------------------------------
|
|
601
|
+
|
|
602
|
+
/** Stub -- SignalWire doesn't use the LiveKit room abstraction. */
|
|
603
|
+
export class Room {
|
|
604
|
+
readonly name: string = 'livewire-room';
|
|
605
|
+
}
|
|
606
|
+
|
|
607
|
+
// ---------------------------------------------------------------------------
|
|
608
|
+
// JobContext
|
|
609
|
+
// ---------------------------------------------------------------------------
|
|
610
|
+
|
|
611
|
+
/** Mirrors a LiveKit JobContext -- provides room and connection info. */
|
|
612
|
+
export class JobContext {
|
|
613
|
+
room: Room;
|
|
614
|
+
proc: JobProcess;
|
|
615
|
+
/** @internal */
|
|
616
|
+
_swAgent?: AgentBase;
|
|
617
|
+
|
|
618
|
+
constructor() {
|
|
619
|
+
this.room = new Room();
|
|
620
|
+
this.proc = new JobProcess();
|
|
621
|
+
}
|
|
622
|
+
|
|
623
|
+
/** Connect is a noop on SignalWire -- the platform handles connection lifecycle. */
|
|
624
|
+
async connect(): Promise<void> {
|
|
625
|
+
globalNoop.once(
|
|
626
|
+
'connect',
|
|
627
|
+
"JobContext.connect(): SignalWire's control plane handles connection lifecycle at scale automatically",
|
|
628
|
+
);
|
|
629
|
+
}
|
|
630
|
+
|
|
631
|
+
/** Wait for a participant -- noop on SignalWire. */
|
|
632
|
+
async waitForParticipant(options?: { identity?: string }): Promise<any> {
|
|
633
|
+
return { identity: options?.identity ?? 'caller' };
|
|
634
|
+
}
|
|
635
|
+
}
|
|
636
|
+
|
|
637
|
+
// ---------------------------------------------------------------------------
|
|
638
|
+
// defineAgent
|
|
639
|
+
// ---------------------------------------------------------------------------
|
|
640
|
+
|
|
641
|
+
/**
|
|
642
|
+
* Mirrors @livekit/agents defineAgent().
|
|
643
|
+
* Wraps an entry function (and optional prewarm) for later execution by runApp.
|
|
644
|
+
*/
|
|
645
|
+
export function defineAgent(agent: {
|
|
646
|
+
entry: (ctx: JobContext) => Promise<void>;
|
|
647
|
+
prewarm?: (proc: JobProcess) => any;
|
|
648
|
+
}): { entry: (ctx: JobContext) => Promise<void>; prewarm?: (proc: JobProcess) => any } {
|
|
649
|
+
return agent;
|
|
650
|
+
}
|
|
651
|
+
|
|
652
|
+
// ---------------------------------------------------------------------------
|
|
653
|
+
// runApp
|
|
654
|
+
// ---------------------------------------------------------------------------
|
|
655
|
+
|
|
656
|
+
/**
|
|
657
|
+
* Mirrors cli.runApp() from @livekit/agents-js.
|
|
658
|
+
*
|
|
659
|
+
* 1. Prints the LiveWire banner
|
|
660
|
+
* 2. Prints a random tip
|
|
661
|
+
* 3. Creates a SignalWire AgentBase from the LiveKit-style config
|
|
662
|
+
* 4. Calls the entry function with a fake JobContext
|
|
663
|
+
* 5. Maps tools from llm.tool() format to SignalWire defineTool format
|
|
664
|
+
* 6. Starts the agent with agent.run()
|
|
665
|
+
*/
|
|
666
|
+
export function runApp(options: any): void {
|
|
667
|
+
printBanner();
|
|
668
|
+
|
|
669
|
+
// If passed an AgentServer instance, convert it to an agentDef-compatible object
|
|
670
|
+
const agentDef = options instanceof AgentServer
|
|
671
|
+
? options._toAgentDef()
|
|
672
|
+
: (options?.agent ?? options);
|
|
673
|
+
|
|
674
|
+
// Run prewarm if registered
|
|
675
|
+
if (agentDef?.prewarm) {
|
|
676
|
+
const proc = new JobProcess();
|
|
677
|
+
globalNoop.once(
|
|
678
|
+
'prewarm',
|
|
679
|
+
"prewarm: Warm process pools not needed — SignalWire's control plane manages media infrastructure at scale",
|
|
680
|
+
);
|
|
681
|
+
agentDef.prewarm(proc);
|
|
682
|
+
}
|
|
683
|
+
|
|
684
|
+
// Create a JobContext
|
|
685
|
+
const ctx = new JobContext();
|
|
686
|
+
|
|
687
|
+
// Print a random tip
|
|
688
|
+
printTip();
|
|
689
|
+
|
|
690
|
+
// Call the entry function
|
|
691
|
+
const entryFn = agentDef?.entry ?? agentDef;
|
|
692
|
+
if (typeof entryFn === 'function') {
|
|
693
|
+
Promise.resolve(entryFn(ctx)).then(() => {
|
|
694
|
+
// After entry completes, the session should have bound a swAgent to ctx
|
|
695
|
+
// If someone stored it on ctx, start it
|
|
696
|
+
if (ctx._swAgent) {
|
|
697
|
+
ctx._swAgent.run().catch((err: Error) => {
|
|
698
|
+
process.stderr.write(`[LiveWire] agent error: ${err.message}\n`);
|
|
699
|
+
});
|
|
700
|
+
}
|
|
701
|
+
}).catch((err: Error) => {
|
|
702
|
+
process.stderr.write(`[LiveWire] entry function error: ${err.message}\n`);
|
|
703
|
+
});
|
|
704
|
+
}
|
|
705
|
+
}
|
|
706
|
+
|
|
707
|
+
// ---------------------------------------------------------------------------
|
|
708
|
+
// WorkerOptions / ServerOptions
|
|
709
|
+
// ---------------------------------------------------------------------------
|
|
710
|
+
|
|
711
|
+
/** Stub for LiveKit WorkerOptions. */
|
|
712
|
+
export class WorkerOptions {
|
|
713
|
+
constructor(_opts?: any) {}
|
|
714
|
+
}
|
|
715
|
+
|
|
716
|
+
/** Stub for LiveKit ServerOptions. */
|
|
717
|
+
export class ServerOptions {
|
|
718
|
+
constructor(_opts?: any) {}
|
|
719
|
+
}
|
|
720
|
+
|
|
721
|
+
// ---------------------------------------------------------------------------
|
|
722
|
+
// AgentServer
|
|
723
|
+
// ---------------------------------------------------------------------------
|
|
724
|
+
|
|
725
|
+
/**
|
|
726
|
+
* Mirrors a LiveKit AgentServer -- registers entrypoints and starts.
|
|
727
|
+
*
|
|
728
|
+
* Usage:
|
|
729
|
+
* const server = new AgentServer();
|
|
730
|
+
* server.setupFnc = async (proc) => { ... };
|
|
731
|
+
*
|
|
732
|
+
* // Bare decorator usage:
|
|
733
|
+
* server.rtcSession(myEntryFn);
|
|
734
|
+
*
|
|
735
|
+
* // Parameterized decorator usage:
|
|
736
|
+
* server.rtcSession({ agentName: 'myAgent' })(myEntryFn);
|
|
737
|
+
*
|
|
738
|
+
* cli.runApp(server);
|
|
739
|
+
*/
|
|
740
|
+
export class AgentServer {
|
|
741
|
+
/** Optional prewarm hook called before the entrypoint. Mirrors Python's setup_fnc. */
|
|
742
|
+
setupFnc?: (proc: JobProcess) => void;
|
|
743
|
+
|
|
744
|
+
/** @internal Registered entrypoint function. */
|
|
745
|
+
private _entryFn?: (ctx: JobContext) => Promise<void>;
|
|
746
|
+
|
|
747
|
+
/** @internal Agent name hint registered via rtcSession(). */
|
|
748
|
+
private _agentName: string = '';
|
|
749
|
+
|
|
750
|
+
constructor(_opts?: any) {}
|
|
751
|
+
|
|
752
|
+
/**
|
|
753
|
+
* Decorator that registers the session entrypoint.
|
|
754
|
+
*
|
|
755
|
+
* Supports both bare and parameterized usage:
|
|
756
|
+
* server.rtcSession(fn) // bare
|
|
757
|
+
* server.rtcSession(fn, { agentName: 'x' }) // with opts, explicit fn
|
|
758
|
+
* server.rtcSession({ agentName: 'x' })(fn) // parameterized decorator
|
|
759
|
+
* @server.rtcSession // decorator (bare)
|
|
760
|
+
* @server.rtcSession({ agentName: 'x' }) // decorator (parameterized)
|
|
761
|
+
*/
|
|
762
|
+
rtcSession(
|
|
763
|
+
fnOrOpts?:
|
|
764
|
+
| ((ctx: JobContext) => Promise<void>)
|
|
765
|
+
| {
|
|
766
|
+
agentName?: string;
|
|
767
|
+
type?: string;
|
|
768
|
+
onRequest?: ((...args: any[]) => any) | null;
|
|
769
|
+
onSessionEnd?: ((...args: any[]) => any) | null;
|
|
770
|
+
},
|
|
771
|
+
opts?: {
|
|
772
|
+
agentName?: string;
|
|
773
|
+
type?: string;
|
|
774
|
+
onRequest?: ((...args: any[]) => any) | null;
|
|
775
|
+
onSessionEnd?: ((...args: any[]) => any) | null;
|
|
776
|
+
},
|
|
777
|
+
): ((fn: (ctx: JobContext) => Promise<void>) => (ctx: JobContext) => Promise<void>) | void {
|
|
778
|
+
// Determine whether first arg is a function or an options object
|
|
779
|
+
let fn: ((ctx: JobContext) => Promise<void>) | undefined;
|
|
780
|
+
let resolvedOpts: typeof opts;
|
|
781
|
+
|
|
782
|
+
if (typeof fnOrOpts === 'function') {
|
|
783
|
+
fn = fnOrOpts;
|
|
784
|
+
resolvedOpts = opts;
|
|
785
|
+
} else {
|
|
786
|
+
// fnOrOpts is an options object (or undefined) — parameterized decorator usage
|
|
787
|
+
resolvedOpts = fnOrOpts;
|
|
788
|
+
}
|
|
789
|
+
|
|
790
|
+
if (resolvedOpts?.type && resolvedOpts.type !== 'room') {
|
|
791
|
+
globalNoop.once(
|
|
792
|
+
'server_type',
|
|
793
|
+
`AgentServer.rtcSession(type=${JSON.stringify(resolvedOpts.type)}): SignalWire's control plane handles server topology at scale automatically`,
|
|
794
|
+
);
|
|
795
|
+
}
|
|
796
|
+
|
|
797
|
+
const register = (entryFn: (ctx: JobContext) => Promise<void>) => {
|
|
798
|
+
this._entryFn = entryFn;
|
|
799
|
+
if (resolvedOpts?.agentName) this._agentName = resolvedOpts.agentName;
|
|
800
|
+
return entryFn;
|
|
801
|
+
};
|
|
802
|
+
|
|
803
|
+
if (fn) {
|
|
804
|
+
register(fn);
|
|
805
|
+
return;
|
|
806
|
+
}
|
|
807
|
+
return register;
|
|
808
|
+
}
|
|
809
|
+
|
|
810
|
+
/** @internal Extract agentDef-compatible shape for use by runApp. */
|
|
811
|
+
_toAgentDef(): {
|
|
812
|
+
entry: (ctx: JobContext) => Promise<void>;
|
|
813
|
+
prewarm?: (proc: JobProcess) => void;
|
|
814
|
+
} {
|
|
815
|
+
return {
|
|
816
|
+
entry: this._entryFn ?? (async (_ctx: JobContext) => {}),
|
|
817
|
+
prewarm: this.setupFnc,
|
|
818
|
+
};
|
|
819
|
+
}
|
|
820
|
+
}
|
|
821
|
+
|
|
822
|
+
// ---------------------------------------------------------------------------
|
|
823
|
+
// Plugin stubs
|
|
824
|
+
// ---------------------------------------------------------------------------
|
|
825
|
+
|
|
826
|
+
/** Stub providers matching common LiveKit plugin packages. */
|
|
827
|
+
export namespace plugins {
|
|
828
|
+
export class DeepgramSTT {
|
|
829
|
+
constructor(_opts?: any) {
|
|
830
|
+
globalNoop.once(
|
|
831
|
+
'stt_plugin',
|
|
832
|
+
'DeepgramSTT: SignalWire\'s control plane handles the full media pipeline at scale',
|
|
833
|
+
);
|
|
834
|
+
}
|
|
835
|
+
}
|
|
836
|
+
|
|
837
|
+
export class OpenAILLM {
|
|
838
|
+
model: string;
|
|
839
|
+
constructor(_opts?: any) {
|
|
840
|
+
this.model = ((_opts as any)?.model as string) ?? '';
|
|
841
|
+
globalNoop.once(
|
|
842
|
+
'openai_llm',
|
|
843
|
+
'OpenAILLM(): model selection is mapped to SignalWire AI params -- OpenAI plugin wrapper is a no-op',
|
|
844
|
+
);
|
|
845
|
+
}
|
|
846
|
+
}
|
|
847
|
+
|
|
848
|
+
export class CartesiaTTS {
|
|
849
|
+
constructor(_opts?: any) {
|
|
850
|
+
globalNoop.once(
|
|
851
|
+
'cartesia_tts',
|
|
852
|
+
"CartesiaTTS: SignalWire's control plane handles the full media pipeline at scale",
|
|
853
|
+
);
|
|
854
|
+
}
|
|
855
|
+
}
|
|
856
|
+
|
|
857
|
+
export class ElevenLabsTTS {
|
|
858
|
+
constructor(_opts?: any) {
|
|
859
|
+
globalNoop.once(
|
|
860
|
+
'elevenlabs_tts',
|
|
861
|
+
"ElevenLabsTTS: SignalWire's control plane handles the full media pipeline at scale",
|
|
862
|
+
);
|
|
863
|
+
}
|
|
864
|
+
}
|
|
865
|
+
|
|
866
|
+
export class SileroVAD {
|
|
867
|
+
constructor(_opts?: Record<string, unknown>) {}
|
|
868
|
+
|
|
869
|
+
static load(): SileroVAD {
|
|
870
|
+
globalNoop.once(
|
|
871
|
+
'vad_plugin',
|
|
872
|
+
"SileroVAD.load(): SignalWire's control plane handles voice activity detection at scale automatically",
|
|
873
|
+
);
|
|
874
|
+
return new SileroVAD();
|
|
875
|
+
}
|
|
876
|
+
}
|
|
877
|
+
}
|
|
878
|
+
|
|
879
|
+
// ---------------------------------------------------------------------------
|
|
880
|
+
// Inference module stubs
|
|
881
|
+
// ---------------------------------------------------------------------------
|
|
882
|
+
|
|
883
|
+
/** Stub inference types matching LiveKit's inference namespace. */
|
|
884
|
+
export namespace inference {
|
|
885
|
+
export class STT {
|
|
886
|
+
model: string;
|
|
887
|
+
constructor(model: string = '', _opts?: any) {
|
|
888
|
+
this.model = model;
|
|
889
|
+
globalNoop.once(
|
|
890
|
+
'inference_stt',
|
|
891
|
+
'inference.STT: SignalWire\'s control plane handles speech recognition at scale',
|
|
892
|
+
);
|
|
893
|
+
}
|
|
894
|
+
}
|
|
895
|
+
|
|
896
|
+
export class LLM {
|
|
897
|
+
model: string;
|
|
898
|
+
constructor(model: string = '', _opts?: any) {
|
|
899
|
+
this.model = model;
|
|
900
|
+
}
|
|
901
|
+
}
|
|
902
|
+
|
|
903
|
+
export class TTS {
|
|
904
|
+
model: string;
|
|
905
|
+
constructor(model: string = '', _opts?: any) {
|
|
906
|
+
this.model = model;
|
|
907
|
+
globalNoop.once(
|
|
908
|
+
'inference_tts',
|
|
909
|
+
'inference.TTS: SignalWire\'s control plane handles text-to-speech at scale',
|
|
910
|
+
);
|
|
911
|
+
}
|
|
912
|
+
}
|
|
913
|
+
}
|
|
914
|
+
|
|
915
|
+
// ---------------------------------------------------------------------------
|
|
916
|
+
// Namespace re-exports matching @livekit/agents
|
|
917
|
+
// ---------------------------------------------------------------------------
|
|
918
|
+
|
|
919
|
+
/** LiveKit voice namespace equivalent. */
|
|
920
|
+
export const voice = {
|
|
921
|
+
Agent,
|
|
922
|
+
AgentSession,
|
|
923
|
+
AgentSessionEventTypes: {} as Record<string, string>,
|
|
924
|
+
};
|
|
925
|
+
|
|
926
|
+
/** Minimal ChatContext matching livekit ChatContext. */
|
|
927
|
+
export class ChatContext {
|
|
928
|
+
messages: Array<Record<string, string>> = [];
|
|
929
|
+
|
|
930
|
+
append(options: { role?: string; text?: string }): this {
|
|
931
|
+
this.messages.push({ role: options.role ?? 'user', content: options.text ?? '' });
|
|
932
|
+
return this;
|
|
933
|
+
}
|
|
934
|
+
}
|
|
935
|
+
|
|
936
|
+
/** LiveKit llm namespace equivalent. */
|
|
937
|
+
export const llm = {
|
|
938
|
+
tool,
|
|
939
|
+
handoff,
|
|
940
|
+
ToolError,
|
|
941
|
+
ChatContext,
|
|
942
|
+
};
|
|
943
|
+
|
|
944
|
+
/** LiveKit cli namespace equivalent. */
|
|
945
|
+
export const cli = {
|
|
946
|
+
runApp,
|
|
947
|
+
};
|
|
948
|
+
|
|
949
|
+
// Re-export banner/tip functions for testing
|
|
950
|
+
export { printBanner, printTip, banner };
|